X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=6609c1b5a6dae6a18d164c395d515f93a6510390;hb=491b29a243ffc0be9f99bb12ac22c65ada8f96c4;hp=fc42aff1771aac4a080f38295944aa2497908045;hpb=28de5c7acd18559872dcaf574c484d758cd50f46;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index fc42aff..ea0d883 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -1,29 +1,40 @@ - - %versiondata; -]> - - + %versiondata; + + %commondata; - Topics to be included: - - add an intro/scope section - - bugs in upstream versions should be reported upstream! - - pointer for useful tools for maintainers + + + + - --> + + FIXME: "> +]> + - Debian Developer's Reference - <author>Adam P. Harris, current maintainer <email/aph@debian.org/ - <author>Christian Schwarz <email/schwarz@debian.org/ - <author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/ - <version>version &version;, &date; + + <author>Developer's Reference Team &email-devel-ref; + <author>Adam Di Carlo, editor + <author>Raphaël Hertzog + <author>Christian Schwarz + <author>Ian Jackson + <version>ver. &version;, &date-en; <copyright> -Copyright ©1998 Adam P. Harris. Copyright ©1997,1998 -Christian Schwarz. + <copyrightsummary> +copyright © 1998—2003 Adam Di Carlo</copyrightsummary> + <copyrightsummary> +copyright © 2002—2003 Raphaël Hertzog</copyrightsummary> + <copyrightsummary> +copyright © 1997, 1998 Christian Schwarz</copyrightsummary> <p> This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the @@ -35,872 +46,4499 @@ This is distributed in the hope that it will be useful, but merchantability or fitness for a particular purpose. See the GNU General Public License for more details. <p> -A copy of the GNU General Public License is available as -<tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux distribution -or on the World Wide Web at <url -id="http://www.gnu.org/copyleft/gpl.html">. You can also obtain it by -writing to the Free Software Foundation, Inc., 59 Temple Place - Suite -330, Boston, MA 02111-1307, USA. +A copy of the GNU General Public License is available as &file-GPL; in +the &debian-formal; distribution or on the World Wide Web at <url +id="&url-gpl;" name="the GNU web site">. You can also obtain it by +writing to the &fsf-addr;. + + <toc detail="sect1"> + + <chapt id="scope">Scope of This Document + <p> +The purpose of this document is to provide an overview of the +recommended procedures and the available resources for Debian +developers. + +<!-- FIXME: rewrites --> + <p> +The procedures discussed within include how to become a maintainer +(<ref id="new-maintainer">); how to create new packages +(<ref id="newpackage">) and how to upload packages (<ref id="upload">); +how to handle bug reports (<ref id="bug-handling">); how to move, +remove, or orphan packages (<ref id="archive-manip">); how to port +packages (<ref id="porting">); and how and when to do interim +releases of other maintainers' packages (<ref id="nmu">). + <p> +The resources discussed in this reference include the mailing lists +(<ref id="mailing-lists">) and servers (<ref id="server-machines">); a +discussion of the structure of the Debian archive (<ref +id="archive">); explanation of the different servers which accept +package uploads (<ref id="upload-ftp-master">); and a discussion of +resources which can help maintainers with the quality of their +packages (<ref id="tools">). + <p> +It should be clear that this reference does not discuss the technical +details of the Debian package nor how to generate Debian packages. +Nor does this reference detail the standards to which Debian software +must comply. All of such information can be found in the <url +id="&url-debian-policy;" name="Debian Policy Manual">. + <p> +Furthermore, this document is <em>not an expression of formal +policy</em>. It contains documentation for the Debian system and +generally agreed-upon best practices. Thus, it is what is called a +``normative'' document. - <toc sect> - <chapt>Applying to Become a Maintainer + <chapt id="new-maintainer">Applying to Become a Maintainer - <sect>Getting started - <p> -So, you've read all the documentation, you understand what everything -in the <prgn/hello/ example package is for, and you're about to -Debianise your favourite package. How do you actually become a Debian -developer so that your work can be incorporated into the Project? - <p> -Firstly, subscribe to <email/debian-devel@lists.debian.org/ if you -haven't already. Send the word <tt/subscribe/ in the <em/Subject/ of -a mail to <email/debian-devel-REQUEST@lists.debian.org/. In case of -problems contact the list administrator at -<email/listmaster@lists.debian.org/. - <p> -You should subscribe and lurk for a bit before doing any coding, and -you should post about your intentions to work on something to avoid -duplicated effort. - <p> -If you do not have a PGP key yet, generate one. You should probably -read the PGP manual, since it has much important information which is -critical to its security. Many more security failures are due to -human error than to software failure or high-powered spy techniques. - <p> -Due to export restrictions by the United States government some Debian -packages, including PGP, have been moved to an ftp site outside of the -United States. You can find the current locations of those packages on -<ftpsite/ftp.debian.org/ or <ftpsite/ftp.us.debian.org/ in the -<ftppath>/pub/debian/README.non-US</ftppath> file. - <p> -If you live in a country where use of cryptography even for -authentication is forbidden then please contact us so we can make -special arrangements. This does not apply in France, where I believe -only encryption and not authentication is forbidden. - - - <sect>Registering as a Debian developer - <p> -Before you decide to work in the Debian Project you have to read the -<url id="http://www.debian.org/social_contract" name="Debian Social -Contract">. - <p> -After that, you should send a message to -<email/new-maintainer@debian.org/ to register as an 'offical' Debian -developer so that you will be able to upload your packages. - <p> -The message should say what you've done and who you are, and should -ask for an account on <tt/master/ and to be subscribed to -<email/debian-private@lists.debian.org/ (the developers-only mailing -list). It should contain your PGP or RSA public key (extracted using -<tt>pgp -kxa</tt> in the case of PGP; note that <tt/gpg/ integration -is underway) for the database of keys which is distributed on the FTP -server (<url -id="ftp://ftp.debian.org/pub/debian/doc/debian-keyring.tar.gz">, or -the <prgn>debian-keyring</prgn>> package). Please be sure to sign -your request message with your chosen PGP or RSA key. In addition, you -have to mention that you've read the ``Debian Social Contract'' (see -above) and you are expected to know where to find the ``Debian Policy -Manual'' and the ``Debian Packaging Manual.'' - <p> -Please be sure to include your preferred login name on <tt/master/ -(seven characters or less), as well as the email address at which -you'd prefer to be subscribed to -<email/debian-private@lists.debian.org/ (typically this will be either -your primary mail address or your new <tt>debian.org</tt> address). - <p> -You should also include some mechanism by which we can verify your -real-life identity. For example, any of the following mechanisms -would suffice: - <list compact> - <item> -A PGP or RSA key signed by any well-known signature, such as any -current Debian developer. - <item> -A scanned (or physically mailed) copy of any formal documents -certifying your identity (such as a birth certificate, national ID -card, U.S. Driver's License, etc.). Please sign the image with your -PGP or RSA key. - </list> - -The following mechanisms are discouraged, but are acceptable if -neither of the first two mechanisms is practical: - <list compact> - <item> -A pointer to a phone listing at which you could be reached (at our -expense). This phone listing should be verifiable independently -through external means such as a national directory-listing service or -other authoritative source. - <item> -Any other mechanism by which you can establish your real-life identity -with reasonable certainty. - </list> - -We're sorry about the inconvenience of requiring proof of identity, -but for the moment, such measures are unfortunately the only way we -can ensure the security and reliability of our distribution. + <sect id="getting-started">Getting started <p> -Once this information is received and processed, you should be -contacted with information about your new Debian maintainer account. -If you don't hear anything within 7-10 days, please re-send your -original message--the new-maintainer volunteers are typically -overworked, and mistakes do occasionally happen. +So, you've read all the documentation, you've gone through the <url +id="&url-newmaint-guide;" name="Debian New Maintainers' Guide">, +understand what everything in the <package>hello</package> example +package is for, and you're about to Debianize your favorite piece of +software. How do you actually become a Debian developer so that your +work can be incorporated into the Project? + <p> +Firstly, subscribe to &email-debian-devel; if you haven't already. +Send the word <tt>subscribe</tt> in the <em>Subject</em> of an email +to &email-debian-devel-req;. In case of problems, contact the list +administrator at &email-listmaster;. More information on available +mailing lists can be found in <ref id="mailing-lists">. +&email-debian-devel-announce; is another list which is mandatory +for anyone who wishes to follow Debian's development. + <p> +You should subscribe and lurk (that is, read without posting) for a +bit before doing any coding, and you should post about your intentions +to work on something to avoid duplicated effort. + <p> +Another good list to subscribe to is &email-debian-mentors;. See <ref +id="mentors"> for details. The IRC channel <tt>#debian</tt> can also be +helpful. + + <p> +When you know how you want to contribute to &debian-formal;, you +should get in contact with existing Debian maintainers who are working +on similar tasks. That way, you can learn from experienced developers. +For example, if you are interested in packaging existing software for +Debian you should try to get a sponsor. A sponsor will work together +with you on your package and upload it to the Debian archive once they +are happy with the packaging work you have done. You can find a sponsor +by mailing the &email-debian-mentors; mailing list, describing your +package and yourself and asking for a sponsor (see <ref id="sponsoring"> +for more information on sponsoring). On the other hand, if you are +interested in porting Debian to alternative architectures or kernels +you can subscribe to port specific mailing lists and ask there how to +get started. Finally, if you are interested in documentation or +Quality Assurance (QA) work you can join maintainers already working on +these tasks and submit patches and improvements. + + <sect id="registering">Registering as a Debian developer + <p> +Before you decide to register with &debian-formal;, you will need to +read all the information available at the <url id="&url-newmaint;" +name="New Maintainer's Corner">. It describes exactly the +preparations you have to do before you can register to become a Debian +developer. - <sect>Debian Mentors +For example, before you apply, you have to to read the <url +id="&url-social-contract;" name="Debian Social Contract">. +Registering as a developer means that you agree with and pledge to +uphold the Debian Social Contract; it is very important that +maintainers are in accord with the essential ideas behind +&debian-formal;. Reading the <url id="&url-gnu-manifesto;" name="GNU +Manifesto"> would also be a good idea. <p> -There is a mailing list called <email/debian-mentors@lists.debian.org/ -which has been set up for newbie maintainers who seek help with -initial packaging and other developer-related issues. +The process of registering as a developer is a process of verifying +your identity and intentions, and checking your technical skills. As +the number of people working on &debian-formal; has grown to over +&number-of-maintainers; people and our systems are used in several +very important places we have to be careful about being compromised. +Therefore, we need to verify new maintainers before we can give them +accounts on our servers and let them upload packages. <p> -Every new developer is invited to subscribe to that list (see <ref -id="mailing-lists"> for details). +Before you actually register you should have shown that you can do +competent work and will be a good contributor. You can show this by +submitting patches through the Bug Tracking System or having a package +sponsored by an existing maintainer for a while. Also, we expect that +contributors are interested in the whole project and not just in +maintaining their own packages. If you can help other maintainers by +providing further information on a bug or even a patch, then do so! <p> -Those who prefer one-on-one help (e.g., via private emails) should -also post to that list and an experienced developer will volunteer to -help. +Registration requires that you are familiar with Debian's philosophy +and technical documentation. Furthermore, you need a GnuPG key which +has been signed by an existing Debian maintainer. If your GnuPG key +is not signed yet, you should try to meet a Debian maintainer in +person to get your key signed. There's a <url id="&url-gpg-coord;" +name="GnuPG Key Signing Coordination page"> which should help you find +a maintainer close to you (If you cannot find a Debian maintainer +close to you, there's an alternative way to pass the ID check. You +can send in a photo ID signed with your GnuPG key. Having your GnuPG +key signed is the preferred way, however. See the +<url id="&url-newmaint-id;" name="identification page"> for more +information about these two options.) + <p> +If you do not have an OpenPGP key yet, generate one. Every developer +needs a OpenPGP key in order to sign and verify package uploads. You +should read the manual for the software you are using, since it has +much important information which is critical to its security. Many +more security failures are due to human error than to software failure +or high-powered spy techniques. See <ref id="key-maint"> for more +information on maintaining your public key. + <p> +Debian uses the <prgn>GNU Privacy Guard</prgn> (package +<package>gnupg</package> version 1 or better) as its baseline standard. +You can use some other implementation of OpenPGP as well. Note that +OpenPGP is an open standard based on <url id="&url-rfc2440;" name="RFC +2440">. + <p> +The recommended public key algorithm for use in Debian development +work is DSA (sometimes call ``DSS'' or ``DH/ElGamal''). Other key +types may be used however. Your key length must be at least 1024 +bits; there is no reason to use a smaller key, and doing so would be +much less secure. Your key must be signed with at least your own user +ID; this prevents user ID tampering. <prgn>gpg</prgn> does this +automatically. + <p> +If your public key isn't on public key servers such as &pgp-keyserv;, +please read the documentation available locally in &file-keyservs;. +That document contains instructions on how to put your key on the +public key servers. The New Maintainer Group will put your public key +on the servers if it isn't already there. + <p> +Some countries restrict the use of cryptographic software by their +citizens. This need not impede one's activities as a Debian package +maintainer however, as it may be perfectly legal to use cryptographic +products for authentication, rather than encryption purposes. +&debian-formal; does not require the use of cryptography <em>qua</em> +cryptography in any manner. If you live in a country where use of +cryptography even for authentication is forbidden +then please contact us so we can make special arrangements. + <p> +To apply as a new maintainer, you need an existing Debian maintainer +to verify your application (an <em>advocate</em>). After you have +contributed to Debian for a while, and you want to apply to become a +registered developer, an existing developer with whom you +have worked over the past months has to express his belief that you +can contribute to Debian successfully. + <p> +When you have found an advocate, have your GnuPG key signed and have +already contributed to Debian for a while, you're ready to apply. +You can simply register on our <url id="&url-newmaint-apply;" +name="application page">. After you have signed up, your advocate +has to confirm your application. When your advocate has completed +this step you will be assigned an Application Manager who will +go with you through the necessary steps of the New Maintainer process. +You can always check your status on the <url id="&url-newmaint-db;" +name="applications status board">. + <p> +For more details, please consult <url id="&url-newmaint;" name="New +Maintainer's Corner"> at the Debian web site. Make sure that you +are familiar with the necessary steps of the New Maintainer process +before actually applying. If you are well prepared, you can save +a lot of time later on. - <chapt>Internet Servers - <sect id="mailing-lists">Mailing lists + <sect id="mentors">Debian mentors and sponsors <p> -The mailing list server is at <tt/lists.debian.org/. Mail -<tt/debian-<var/foo/-REQUEST@lists.debian.org/, where -<tt/debian-<var/foo// is the name of the list, with the word -<tt/subscribe/ in the Subject to subscribe or <tt/unsubscribe/ to -unsubscribe. +The mailing list &email-debian-mentors; has been set up for novice +maintainers who seek help with initial packaging and other +developer-related issues. Every new developer is invited to subscribe +to that list (see <ref id="mailing-lists"> for details). <p> -When replying to messages on the mailing list, please do not send a -carbon copy (<tt/CC/--this does not mean `courtesy copy') to the -original poster. Anyone who posts to a mailing list should read it to -see the responses. - <p> -In addition, all messages should usually only be sent to one of the -following mailing lists: <email/debian-devel@lists.debian.org/, -<email/debian-policy@lists.debian.org/, -<email/debian-user@lists.debian.org/, -<email/debian-announce@lists.debian.org/, or -<email/debian-devel-announce@lists.debian.org/. Cross-posting is -discouraged. +Those who prefer one-on-one help (e.g., via private email) should also +post to that list and an experienced developer will volunteer to help. <p> -As ever on the net, please trim down the quoting of articles you're -replying to. In general, please adhere to the usual conventions for -posting messages. +In addition, if you have some packages ready for inclusion in Debian, +but are waiting for your new maintainer application to go through, you +might be able find a sponsor to upload your package for you. Sponsors +are people who are official Debian maintainers, and who are willing to +criticize and upload your packages for you. Those who are seeking a +sponsor can request one at <url id="&url-sponsors;">. + <p> +If you wish to be a mentor and/or sponsor, more information is +available in <ref id="newmaint">. - <sect>The master server - <p> -The master server, <tt/master.debian.org/, holds the cannonical copy -of the Debian archive (excluding the non-U.S. packages). Generally, -package uploads go to this server; cf. <ref id="upload">. All Debian -developers have accounts on this machine. + <chapt id="developer-duties">Debian Developer's Duties - <sect>The FTP servers + <sect id="user-maint">Maintaining your Debian information <p> - - <sect>The WWW servers +There's a LDAP database containing information about Debian developers at +<url id="&url-debian-db;">. You should enter your information there and +update it as it changes. Most notably, make sure that the address where your +debian.org email gets forwarded to is always up to date, as well as the +address where you get your debian-private subscription if you choose to +subscribe there. <p> +For more information about the database, please see <ref id="devel-db">. - <chapt>The Debian Archive - <sect>Overview + <sect id="key-maint">Maintaining your public key <p> -The Debian GNU/Linux distribution consists of a lot of Debian packages -(<tt/.deb/'s, currently more than 1500) and a few additional files -(documentation, installation disk images, etc.). +Be very careful with your private keys. Do not place them on any +public servers or multiuser machines, such as the Debian servers +(see <ref id="server-machines">). Back your keys up; keep a copy offline. +Read the documentation that comes with your software; read the <url +id="&url-pgp-faq;" name="PGP FAQ">. <p> -Here is an example directory tree of a complete Debian distribution: -<example> -main/ -main/binary-all/ -main/binary-all/admin/ -main/binary-all/base/ -main/binary-all/comm/ -main/binary-all/devel/ - ... -main/binary-i386/ -main/binary-m86k/ - ... -main/source/ -main/disks-i386/ -main/disks-m68k/ - ... - -contrib/ -contrib/binary-all/ -contrib/binary-i386/ -contrib/binary-m86k/ - ... -contrib/source/ - -non-free/ -non-free/binary-all/ -non-free/binary-i386/ -non-free/binary-m86k/ - ... -non-free/source/ -</example> +If you add signatures to your public key, or add user identities, you +can update the Debian key ring by sending your key to the key server at +<tt>&keyserver-host;</tt>. If you need to add a completely new key, +or remove an old key, send mail to &email-debian-keyring;. The same +key extraction routines discussed in <ref id="registering"> apply. <p> -As you can see, the top-level directory of the distribution contains -three directories, namely <em>main</>, <em>contrib</>, and -<em>non-free</>. These directories are called <em>sections</>. +You can find a more in-depth discussion of Debian key maintenance in +the documentation of the <package>debian-keyring</package> package. + + + <sect id="voting">Voting <p> -In each section, there is a directory with the source packages -(source), a directory for each supported architecture (binary-i386, -binary-m86k, etc.), and a directory for architecture independent -packages (binary-all). +Even though Debian isn't really a democracy, we use a democratic +process to elect our leaders and to approve general resolutions. +These procedures are defined by the +<url id="&url-constitution;" name="Debian Constitution">. <p> -The <em/main/ section contains additional directories which holds the -disk images and some essential pieces of documentation required for -installing the Debian distribution on a specific architecture -(disks-i386, disks-m68k, etc.). +Other than the yearly leader election, votes are not routinely held, and +they are not undertaken lightly. Each proposal is first discussed on +the &email-debian-vote; mailing list and it requires several endorsements +before the project secretary starts the voting procedure. <p> -The <em/binary/ and <em/source/ directories are divided further into -<em/subsections/. +You don't have to track the pre-vote discussions, as the secretary will +issue several calls for votes on &email-debian-devel-announce; (and all +developers are expected to be subscribed to that list). Democracy doesn't +work well if people don't take part in the vote, which is why we encourage +all developers to vote. Voting is conducted via GPG-signed/encrypted emails +messages. + <p> +The list of all the proposals (past and current) is available on the +<url id="&url-vote;" name="Debian Voting Information"> page, along with +information on how to make, second and vote on proposals. - <sect>Sections + <sect id="inform-vacation">Going on vacation gracefully <p> -The <em>main</em> section is what makes up the <em>Debian GNU/Linux -distribution</>. This is because the packages in the other two -sections do not fully comply with all our guidelines. As such, they -are not officially part of Debian. +It is common for developers to have periods of absence, whether those are +planned vacations or simply being buried in other work. The important thing +to notice is that the other developers need to know that you're on vacation +so that they can do whatever is needed if a problem occurs with your +packages or other duties in the project. <p> -For example, every package in the main distribution must fully comply -with the <em>Debian Free Software Guidelines</> (DFSG) and with all -other policy requirements as described in the <em>Debian Policy -Manual</em>. (The DFSG is our definition of ``free software.'' Check -out the Debian Policy Manual for details.) +Usually this means that other developers are allowed to NMU (see +<ref id="nmu">) your package if a big problem (release critical bugs, +security update, etc.) occurs while you're on vacation. Sometimes it's +nothing as critical as that, but it's still appropriate to let the others +know that you're unavailable. <p> -The packages which do not apply to the DFSG are placed in the -<em>non-free</> section. These packages are not considered as part of -the Debian distribution, though we support their use, and we provide -infrastructure (such as our bug-tracking system and mailing lists) for -non-free software packages. +In order to inform the other developers, there's two things that you should do. +First send a mail to &email-debian-private; with "[VAC] " prepended to the +subject of your message<footnote>This is so that the message can be easily +filtered by people who don't want to read vacation notices.</footnote> +and state the period of time when you will be on vacation. You can also give +some special instructions on what to do if a problem occurs. <p> -Packages in the <em>contrib</> section have to apply to the DFSG, but -fail other requirements. For instance, they might depend on non-free -packages. +The other thing to do is to mark yourself as "on vacation" in the +<qref id="devel-db">Debian developers' LDAP database</qref> (this +information is only accessible to Debian developers). +Don't forget to remove the "on vacation" flag when you come back! + + + <sect id="upstream-coordination">Coordination with upstream developers <p> -(The Debian Policy Manual contains a more exact definition of the -three sections. This is just meant to be an introduction.) +A big part of your job as Debian maintainer will be to stay in contact +with the upstream developers. Debian users will sometimes report bugs +to the Bug Tracking System that are not specific to Debian. You +must forward these bug reports to the upstream developers so that +they can be fixed in a future release. It's not your job to fix +non-Debian specific bugs. However, if you are able to do so, you are +encouraged to contribute to upstream development of the package by +providing a fix for the bug. Debian users and developers will often +submit patches to fix upstream bugs, and you should evaluate and +forward these patches upstream. + <p> +If you need to modify the upstream sources in order to build a policy +compliant package, then you should propose a nice fix to the upstream +developers which can be included there, so that you won't have to +modify the sources of the next upstream version. Whatever changes you +need, always try not to fork from the upstream sources. + + + <sect id="rc-bugs">Managing release-critical bugs + <p> +Generally you should deal with bug reports on your packages as described in +<ref id="bug-handling">. However, there's a special category of bugs that +you need to take care of -- the so-called release-critical bugs (RC bugs). +All bug reports that have severity <em>critical</em>, <em>grave</em> or +<em>serious</em> are considered to have an impact on whether the package can +be released in the next stable release of Debian. +Those bugs can delay the Debian release +and/or can justify the removal of a package at freeze time. That's why +these bugs need to be corrected as quickly as possible. <p> -The separation of the three sections at the top-level of the archive -is important for all people who want to distribute Debian, either via -FTP servers on the Internet or on CD-ROMs: by distributing only the -<em/main/ and <em/contrib/ sections, one can avoid any legal risks. -Some packages in the <em/non-free/ section do not allow commercial -distribution, for example. +Developers who are part of the <url id="&url-debian-qa;" +name="Quality Assurance"> group are following all such bugs, and trying +to help whenever possible. If, for any reason, you aren't able fix an +RC bug in a package of yours within 2 weeks, you should either ask for help +by sending a mail to the Quality Assurance (QA) group +&email-debian-qa;, or explain your difficulties and present a plan to fix +them by sending a mail to the bug report. Otherwise, people +from the QA group may want to do a Non-Maintainer Upload (see +<ref id="nmu">) after trying to contact you (they might not wait as long as +usual before they do their NMU if they have seen no recent activity from you +in the BTS). + + + <sect>Retiring <p> -On the other hand, a CD-ROM vendor could easily check the individual -package licenses of the packages in <em/non-free/ and include as many -on the CD-ROMs as he's allowed. (Since this varies from vendor to -vendor very much, this job can't be done by the Debian developers.) +If you choose to leave the Debian project, you should make sure you do +the following steps: +<enumlist> + <item> +Orphan all your packages, as described in <ref id="orphaning">. + <item> +Send an email about why you are leaving the project to +&email-debian-private;. + <item> +Notify the Debian key ring maintainers that you are leaving by +emailing to &email-debian-keyring;. +</enumlist> + - <sect>Architectures + <chapt id="resources">Resources for Debian Developers + <p> +In this chapter you will find a very brief road map of the Debian +mailing lists, the Debian machines +which may be available to you as a developer, and all the other +resources that are available to help you in your maintainer work. + + <sect id="mailing-lists">Mailing lists <p> -In the first days, the Linux kernel was only available for the Intel -i386 (or greater) platforms, and so was Debian. But when Linux became -more and more popular, the kernel was ported to other architectures, -too. +The mailing list server is at <tt>&lists-host;</tt>. <p> -The Linux 2.0 kernel supports Intel, DEC Alphas, SUN Sparcs, M68000 -machines (like Atari and Amiga), MIPS, and PowerPC. +Online archives of mailing lists are available at <url +id="&url-lists-archives;">. + + <sect1 id="core-devel-mailing-lists">Core development mailing lists + <p> +The core Debian mailing lists that developers should use are: +<list> + <item>&email-debian-devel-announce;, used to announce important things to + developers. + All developers are expected to be subscribed to this list. + </item> + <item>&email-debian-devel;, used to discuss various development related + technical issues. + </item> + <item>&email-debian-policy;, where the Debian Policy is discussed and + voted on. + </item> + <item>&email-debian-project;, used to discuss various non-technical + issues related to the project. + </item> +</list> <p> -Debian GNU/Linux 1.3 is only available for Intel platforms. Debian -2.0 supports Intel and m68k architectures. The next version of Debian -is likely to also support Alpha, PPC, and Sparc architectures, if not -more. +There are +other mailing lists available for a variety of special topics; see +<url id="&url-debian-lists-subscribe;"> for a list. + <sect1 id="mailing-lists-subunsub">Subscribing and unsubscribing + <p> +To subscribe to or unsubscribe from any of the Debian mailing lists, email +<tt>debian-<var>foo</var>-REQUEST@&lists-host;</tt>, where +<tt>debian-<var>foo</var></tt> is the name of the list, with the word +<tt>subscribe</tt> in the <em>Subject</em> to subscribe to the list or +<tt>unsubscribe</tt> to unsubscribe. + <p> +If you prefer to use a web page to subscribe to multiple mailing lists, +there's one at <url id="&url-debian-lists-subscribe;">. + <p> +You can download the current list of mailing lists and basic usage +instructions from <url id="&url-debian-lists-txt;"> +or install the <package>doc-debian</package> package and have it +locally in &file-mail-lists;. - <sect>Subsections + <sect1 id="mailing-lists-rules">Basic rules for use + <p> +When replying to messages on the mailing list, please do not send a +carbon copy (<tt>CC</tt>) to the original poster unless they explicitly +request to be copied. Anyone who posts to a mailing list should read +it to see the responses. <p> -The sections <em/main/, <em/contrib/, and <em/non-free/ are split into -<em/subsections/, to simplify the installation process and the -maintainance of the archive. Subsections are not formally defined, -excepting perhaps for the "base" subsection. Subsections exist simply -to simpilfy the organization and browsing of available packages. -Please check the current Debian distribution to see which sections are -available. +Cross-posting (sending the same message to multiple lists) is discouraged. +As ever on the net, please trim down the quoting of articles you're +replying to. In general, please adhere to the usual conventions for +posting messages. + <p> +Please read the <url name="code of conduct" id="&url-debian-lists;"> +for more information. + <sect1 id="mailing-lists-special">Special lists + <p> +&email-debian-private; is a special mailing list for private +discussions amongst Debian developers. It is meant to be used for +posts which for whatever reason should not be published publicly. +As such, it is a low volume list, and users are urged not to use +&email-debian-private; unless it is really necessary. Moreover, do +<em>not</em> forward email from that list to anyone. Archives of this +list are not available on the web for obvious reasons, but you can see +them using your shell account on <tt>lists.debian.org</tt> and looking +in the <file>~debian/archive/debian-private</file> directory. + <p> +&email-debian-email; is a special mailing list used as a grab-bag +for Debian related correspondence such as contacting upstream authors +about licenses, bugs, etc. or discussing the project with others where it +might be useful to have the discussion archived somewhere. - <sect>Packages + <sect id="irc-channels">IRC channels <p> -There are two types of Debian packages, namely <em/source/ and -<em/binary/ packages. +Several IRC channels are dedicated to Debian's development. They are mainly +hosted on the <url id="&url-openprojects;" name="freenode"> network +(previously known as Open Projects Network). +The <tt>irc.debian.org</tt> DNS entry is an alias to +<tt>irc.freenode.net</tt>. <p> -Source packages consist of either two or three files: a <tt/.dsc/ -file, and either one <tt/.tar.gz/ file or a <tt/.orig.tar.gz/ and a -<tt/.diff.gz/ file. +The main channel for Debian in general is <em>#debian</em>. This is a large, +general-purpose channel where users can find recent news in the topic and +served by bots. <em>#debian</em> is for English speakers; there are also +<em>#debian.de</em>, <em>#debian-fr</em>, <em>#debian-br</em> and other +similarly named channels for speakers of other languages. <p> -If a package is developed specially for Debian and is not distributed -outside of Debian, there is just one <tt/.tar.gz/ file which contains -the sources of the program. - <p> -If a package is distributed elsewhere too, the <tt/.orig.tar.gz/ file -stores the so-called <em/upstream source code/, that is the source -code that's distributed from the <em/upstream maintainer/ (author). In -this case, the <tt/.diff.gz/ contains the changes made by the Debian -maintainer. - <p> -The <tt/.dsc/ lists all components of the source package together with -checksums (md5sums) and some additional info about the package -(maintainer, version, etc.). - - - <sect>Distribution directories - <p> -If you have a look at the Debian FTP server or one of its mirrors, -you'll discover that there is one additional directory level on top of -the directory tree, as described in the previous chapter. These -directories are the <em/distribution directories/. All distributions -are contained in the <tt/dists/ directory in the top-level of the -Debian archive (the symlinks from the top-level directory to the -distributions themselves is for backwards compatability and -deprecated). - <p> -There is always a distribution called <em/stable/ (residing in -<tt>dists/stable</tt>) and one called <em/unstable/ (residing in -<tt>dists/unstable</tt>. This reflects the development process of the -Debian project. +The main channel for Debian development is <em>#debian-devel</em>. +It is a very active channel since usually over 150 people are always +logged in. It's a channel for people who work +on Debian, it's not a support channel (there's <em>#debian</em> for that). +It is however open to anyone who wants to lurk (and learn). Its topic is +commonly full of interesting information for developers. <p> -The ``development'' is done in the <em/unstable/ distribution (that's -why this distribution is sometimes called <em/development -distribution/). Every Debian developer can update his or her packages in -this distribution at any time. Thus, the contents of this distribution -changes from day to day and since no special effort is done to test -this distribution it's sometimes ``unstable.'' - <p> -After about a period of development, the <em/unstable/ distribution is -copied in a new distribution directory, called <em/frozen/. After -that, no changes are allowed to the frozen distribution, except bug -fixes. (That's why it's called ``frozen.'') After another month or a -little longer, the <em/frozen/ distribution is renamed to <em/stable/, -overriding the old <em/stable/ distribution, which is removed at that -time. - <p> -This development cycle is based on the assumption that the `unstable' -distribution becomes `stable' after passing a period of testing as -`frozen'. Unfortunately, even once a distribution is considered -`stable', a few bugs inevitably remain--that's why the stable -distribution is updated every now and then. However, these updates are -tested very carefully and have to be acknowledged individually to -reduce the risk of introducing new bugs. You can find proposed -additions to `stable' in the <tt/proposed-updates/ directory. - <p> -Note, that development is continued during the ``freeze'' period, -since a new `unstable' distribution is be created when the older -`unstable' is moved to `frozen'. - <p> -In summary, there is always a <em/stable/ and an <em/unstable/ -distribution available, and the <em/frozen/ distribution shows up for -a month or so from time to time. - - <sect>Release code names - <p> -Every released Debian distribution has a <em/code name/: Debian 1.1 is -called <em/buzz/, Debian 1.2 <em/rex/, Debian 1.3 <em/bo/, Debian 2.0 -<em/hamm/, Debian 2.1 will be called <em/slink/, etc. There is also a -"pseudo-distribution", called <em/sid/, which is -used to contain packages for architectures which are not yet -officially supported or released by Debian. are intended to be -released for some future distribution. - <p> -Since the Debian has an open development model (i.e., everyone can -participate and follow the development) even the ``development -versions'' (unstable) are distributed via the Internet on the Debian -FTP server. This FTP server is mirrored by lots of other -systems. Thus, if we'd call the directory which contains the -development version simply `unstable', then we would have to rename it -to `stable' when the version is released, which would cause all FTP -mirrors to re-get the whole distribution (which is already very -large!). +Since <em>#debian-devel</em> it's an open channel, you +should not speak there of issues that are discussed in +&email-debian-private;. There's another channel for this purpose, +it's called <em>#debian-private</em> and it's protected by a key. +This key is available in the archives of debian-private in +<file>master.debian.org:&file-debian-private-archive;</file>, +just <prgn>zgrep</prgn> for <em>#debian-private</em> in +all the files. <p> -On the other hand, if we would call the distribution directories -<em>Debian-x.y</em> from the beginning, people would think that Debian -release <em>x.y</> is available. (This happened in the past, where a -CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development -version. That's the reason why the first official Debian release was -1.1, and not 1.0.) +There are other additional channels dedicated to specific subjects. +<em>#debian-bugs</em> is used for coordinating bug squash parties. +<em>#debian-boot</em> is used to coordinate the work on the boot +floppies (i.e., the installer). <em>#debian-doc</em> is +occasionally used to talk about documentation, like the document you are +reading. Other channels are dedicated to an architecture or a set of +packages: <em>#debian-bsd</em>, <em>#debian-kde</em>, <em>#debian-jr</em>, +<em>#debian-edu</em>, +<em>#debian-sf</em> (SourceForge package), <em>#debian-oo</em> (OpenOffice +package) ... <p> -Thus, the names of the distribution directories in the archive should -stay the same during the development period and after the release but -there may be symbolic links, which can be changed. +Some non-English developers' channels exist as well, for example +<em>#debian-devel-fr</em> for +French speaking people interested in Debian's development. <p> -That's why the distribution directories use the <em/code names/ and -there are symbolic links <em/stable/, <em/unstable/, <em/frozen/, -etc., which point to the appriopriate release directories. - +Channels dedicated to Debian also exist on other IRC networks, notably on +the <url name="Open and free technology community (OFTC)" +id="http://www.oftc.net/"> IRC network. - <chapt id="upload">Package uploads - <sect>Announcing new packages + <sect id="doc-rsrcs">Documentation <p> -If you want to create a new package for the Debian distribution, you -should first check the <url -id="http://www.debian.org/doc/prospective-packages.html" -name="Work-Needing and Prospective Packages (WNPP)"> page. Checking -the WNPP ensures that no-one is already working on packaging that -software, and that effort is not duplicated. Assuming no-one else is -already working on your prospective package, you must then send a -short email to <email/debian-devel@lists.debian.org/ describing your -plan to create a new package. You should set the subject of the email -to "intent to package <var/foobar/", substituting the name of the new -package for <var/foobar/. - <p> -There are a number of reasons why we ask maintainers to follow these -steps. - <list compact> - <item> -It helps the (potentially new) maintainer to tap into the experience -of people on the list, and lets them know if any one else is working -on it already. - - <item> -It lets other people thinking about working on the package know that -there already is a volunteer, and efforts may be shared. The "intent -to package" message to <email/debian-devel@lists.debian.org/ will be -picked up the the WNPP maintainer, and your intention will be -published in subsequent versions of the WNPP document. +This document contains a lot of information very useful to Debian developers, +but it can not contain everything. Most of the other interesting documents +are linked from <url id="&url-devel-docs;" name="The Developers' Corner">. +Take the time to browse all the links, you will learn many more things. - <item> -It lets the rest of the maintainers know more about the package than -the one line description and the changelog entry "Initial version" -that generally gets posted to <tt/debian-devel-changes/ by default. - <item> -It is helpful to the people who live off unstable (and form our first -line of testers); we should encourage these people. + <sect id="server-machines">Debian machines + <p> +Debian has several computers working as servers, most of which serve +critical functions in the Debian project. Most of the machines are used +for porting activities, and they all have a permanent connection to the +Internet. + <p> +Most of the machines are available for individual developers to use, +as long as the developers follow the rules set forth in the +<url name="Debian Machine Usage Policies" id="&url-dmup;">. + <p> +Generally speaking, you can use these machines for Debian-related purposes +as you see fit. Please be kind to system administrators, and do not use +up tons and tons of disk space, network bandwidth, or CPU without first +getting the approval of the system administrators. Usually these machines are run by +volunteers. + <p> +Please take care to protect your Debian passwords and SSH keys installed on +Debian machines. Avoid login or upload methods which send passwords over +the Internet in the clear, such as telnet, FTP, POP etc. + <p> +Please do not put any material that doesn't relate to Debian on the Debian +servers, unless you have prior permission. + <p> +The current list of Debian machines is available at +<url id="&url-devel-machines;">. That web page contains machine names, +contact information, information about who can log in, SSH keys etc. + <p> +If you have a problem with the operation of a Debian server, and you +think that the system operators need to be notified of this problem, +the Debian system administrator team is reachable at +<email>debian-admin@lists.debian.org</email>. + <p> +If you have a problem with a certain service, not related to the system +administration (such as packages to be removed from the archive, +suggestions for the web site, etc.), +generally you'll report a bug against a ``pseudo-package''. See <ref +id="submit-bug"> for information on how to submit bugs. - <item> -I think the announcements gives us a better feel of what is going on, -and what is new, in the project. + <sect1 id="servers-bugs">The bugs server + <p> +<tt>&bugs-host;</tt> is the canonical location for the Bug Tracking +System (BTS). If you plan on doing some statistical analysis or +processing of Debian bugs, this would be the place to do it. Please +describe your plans on &email-debian-devel; before implementing +anything, however, to reduce unnecessary duplication of effort or +wasted processing time. + <p> +All Debian developers have accounts on <tt>&bugs-host;</tt>. - <item> -We should not dismiss anybody who installs from unstable and helps us -debug our packages as "fools, fools, you installed from unstable; you -deserve what you get"--we derive a certain benefit from the alpha -testers. + <sect1 id="servers-ftp-master">The ftp-master server + <p> +The <tt>ftp-master.debian.org</tt> server holds the canonical copy of the Debian +archive (excluding the non-US packages). Generally, package uploads +go to this server; see <ref id="upload">. + <p> +Problems with the Debian FTP archive generally need to be reported as +bugs against the <package>ftp.debian.org</package> pseudo-package or +an email to &email-ftpmaster;, but also see the procedures in +<ref id="archive-manip">. - <item> -If we appreciate alpha testers, than any name changes have to be -backwards compatible with the people who already installed the old -package (conflict and replace old package name at a minimum). - </list> + <sect1 id="servers-non-us">The non-US server + <p> +The non-US server, <tt>non-us.debian.org</tt>, +holds the canonical copy of the non-US part of the Debian archive. +If you need to upload a package into one of the non-US sections, upload it +to this server; see <ref id="upload-non-us">. + <p> +Problems with the non-US package archive should generally be submitted as +bugs against the <package>nonus.debian.org</package> pseudo-package (notice +the lack of hyphen between "non" and "us" in the pseudo-package name +— that's for backwards compatibility). Remember to check whether or +not someone else has already reported the problem on the +<url id="http://&bugs-host;/nonus.debian.org" name="Bug Tracking System">. + <sect1 id="servers-www">The www-master server + <p> +The main web server is <tt>www-master.debian.org</tt>. +It holds the official web pages, the face +of Debian for most newbies. + <p> +If you find a problem with the Debian web server, you should generally +submit a bug against the pseudo-package, +<package>www.debian.org</package>. Remember to check whether or not someone +else has already reported the problem on the +<url id="http://&bugs-host;/www.debian.org" name="Bug Tracking System">. - <sect>Uploading a package + <sect1 id="servers-people">The people web server + <p> +<tt>people.debian.org</tt> is the server used +for developers' own web pages about anything related to Debian. + <p> +If you have some Debian-specific information which you want to serve +on the web, you can do this by putting material in the +<file>public_html</file> directory under your home directory on +<tt>people.debian.org</tt>. +This will be accessible at the URL +<tt>http://people.debian.org/~<var>your-user-id</var>/</tt>. + <p> +You should only use this particular location because it will be backed up, +whereas on other hosts it won't. + <p> +Usually the only reason to use a different host is when you need to publish +materials subject to the U.S. export restrictions, in which case you can use +one of the other servers located outside the United States, such as the +aforementioned <tt>non-us.debian.org</tt>. + <p> +Send mail to &email-debian-devel; if you have any questions. - <sect1>Generating the changes file - <p> -When a package is uploaded to the Debian FTP archive, it must be -accompanied by a <tt/.changes/ file which gives directions for its -handling. This is usually generated by <prgn/dpkg-genchanges/. - <p> -This file is a control file with the following fields: -<list compact> - <item><tt/Format/ - <item><tt/Date/ - <item><tt/Source/ - <item><tt/Binary/ - <item><tt/Architecture/ - <item><tt/Version/ - <item><tt/Distribution/ - <item><tt/Urgency/ - <item><tt/Maintainer/ - <item><tt/Description/ - <item><tt/Changes/ - <item><tt/Files/ - </list> + <sect1 id="servers-cvs">The CVS server + <p> +Our CVS server is located on <tt>cvs.debian.org</tt>. + <p> +If you need to use a publicly accessible CVS +server, for instance, to help coordinate work on a package between +many different developers, you can request a CVS area on the server. <p> -All of them are mandatory for a Debian upload. See the list of -control fields in the <em/Debian Packaging Manual/ for the contents of -these fields. - <p> -Notably, the <tt/Distribution/ field, which originates from the -<tt>debian/changelog</tt> file, should indicate which distribution the -package is intended for. There are three possible values for this -field: `stable', `unstable', or `frozen'; these values can also be -combined. For instance, if you have a crucial security fix release of -a package, and the package has not diverged between the `stable' and -`unstable' distributions, then you might put `stable unstable' in the -<tt>debian/changelog</tt>'s distribution field. Or, if Debian has -been frozen, and you want to get a bug-fix release into `frozen', you -would set the distribution to `frozen unstable'. Note that setting -the distribution to `stable' means that the pacakge will be placed -into the <tt>proposed-updates</tt> directory of the Debian archive for -further testing, before it is actually included in `stable'. +Generally, <tt>cvs.debian.org</tt> offers a combination of local CVS +access, anonymous client-server read-only access, and full +client-server access through <prgn>ssh</prgn>. Also, the CVS area can +be accessed read-only via the Web at <url id="&url-cvsweb;">. + <p> +To request a CVS area, send a request via email to +&email-debian-admin;. Include the name of the requested CVS area, +the Debian account that should own the CVS root area, and why you need it. - <p> -The first time a version is uploaded which corresponds to a particular -upstream version the original source tar file should be uploaded and -included in the <tt/.changes/ file; subsequent times the very same tar -file should be used to build the new diffs and <tt/.dsc/ files, and it -need not then be uploaded. - <p> -By default <prgn/dpkg-genchanges/ and <prgn/dpkg-buildpackage/ will -include the original source tar-file if and only if the Debian -revision part of the source version number is <tt/0/ or <tt/1/, -indicating a new upstream version. This behaviour may be modified by -using <tt/-sa/ to always include it or <tt/-sd/ to always leave it -out. - <p> -If no original source is included in the upload then the original -source tar-file used by <prgn/dpkg-source/ when constructing the -<tt/.dsc/ file and diff to be uploaded <em/must/ be byte-for-byte -identical with the one already in the archive. If there is some -reason why this is not the case then the new version of the original -source should be uploaded, possibly by using the <tt/-sa/ flag. - - - <sect1>Checking the package prior to upload - <p> -Before you upload your package, you should do basic testing on it. -Make sure you try the following activities (you'll need to have an -older version of the Debian package around). + + <sect id="devel-db">The Developers Database + <p> +The Developers Database, at <url id="&url-debian-db;">, is an LDAP +directory for managing Debian developer attributes. You can use this +resource to search the list of Debian developers. +Part of this information is also available through +the finger service on Debian servers, try +<prgn>finger yourlogin@db.debian.org</prgn> to see what it reports. + <p> +Developers can <url name="log into the database" id="&url-debian-db-login;"> +to change various information about themselves, such as: <list> - <item> install the package and make sure the software - works + <item>forwarding address for your debian.org email + <item>subscription to debian-private + <item>whether you are on vacation + <item>personal information such as your address, country, + the latitude and longitude of the place where you live + for use in <url name="the world map of Debian developers" + id="&url-worldmap;">, phone and fax numbers, IRC nickname + and web page + <item>password and preferred shell on Debian Project machines +</list> + <p> +Most of the information is not accessible to the public, naturally. +For more information please read the online documentation that you can find +at <url id="&url-debian-db-doc;">. + <p> +One can also submit their SSH keys to be used for authorization on the +official Debian machines, and even add new *.debian.net DNS entries. +Those features are documented at <url id="&url-debian-db-mail-gw;">. + + + <sect id="archive">The Debian archive + <p> +The &debian-formal; distribution consists of a lot of packages +(<file>.deb</file>'s, currently around &number-of-pkgs;) and a few +additional files (such documentation and installation disk images). + <p> +Here is an example directory tree of a complete Debian archive: + <p> +&sample-dist-dirtree; + <p> +As you can see, the top-level directory contains two directories, +<file>dists/</file> and <file>pool/</file>. The latter is a “pool” in which the +packages actually are, and which is handled by the archive maintenance +database and the accompanying programs. The former contains the +distributions, <em>stable</em>, <em>testing</em> and <em>unstable</em>. +The <file>Packages</file> and <file>Sources</file> files in the +distribution subdirectories can reference files in the <file>pool/</file> +directory. The directory tree below each of the distributions is arranged +in an identical manner. What we describe below for <em>stable</em> is +equally applicable to the <em>unstable</em> and <em>testing</em> +distributions. + <p> +<file>dists/stable</file> contains three directories, namely <file>main</file>, +<file>contrib</file>, and <file>non-free</file>. + <p> +In each of the areas, there is a directory for the source packages +(<file>source</file>) and a directory for each supported architecture +(<file>binary-i386</file>, <file>binary-m68k</file>, etc.). + <p> +The <file>main</file> area contains additional directories which holds +the disk images and some essential pieces of documentation required +for installing the Debian distribution on a specific architecture +(<file>disks-i386</file>, <file>disks-m68k</file>, etc.). - <item> upgrade the package from an older version to your - new version - <item> downgrade the package to the previous version - (this tests the <tt/postrm/ and <tt/prerm/ scripts) + <sect1>Sections + <p> +The <em>main</em> section of the Debian archive is what makes up the +<strong>official &debian-formal; distribution</strong>. The +<em>main</em> section is official because it fully complies with all +our guidelines. The other two sections do not, to different degrees; +as such, they are <strong>not</strong> officially part of +&debian-formal;. + <p> +Every package in the main section must fully comply with the <url +id="&url-dfsg;" name="Debian Free Software Guidelines"> (DFSG) and +with all other policy requirements as described in the <url +id="&url-debian-policy;" name="Debian Policy Manual">. The DFSG is +our definition of “free software.” Check out the Debian Policy +Manual for details. + <p> +Packages in the <em>contrib</em> section have to comply with the DFSG, +but may fail other requirements. For instance, they may depend on +non-free packages. + <p> +Packages which do not conform to the DFSG are placed in the +<em>non-free</em> section. These packages are not considered as part +of the Debian distribution, though we support their use, and we +provide infrastructure (such as our bug-tracking system and mailing +lists) for non-free software packages. + <p> +The <url id="&url-debian-policy;" name="Debian Policy Manual"> +contains a more exact definition of the three sections. The above +discussion is just an introduction. + <p> +The separation of the three sections at the top-level of the archive +is important for all people who want to distribute Debian, either via +FTP servers on the Internet or on CD-ROMs: by distributing only the +<em>main</em> and <em>contrib</em> sections, one can avoid any legal +risks. Some packages in the <em>non-free</em> section do not allow +commercial distribution, for example. + <p> +On the other hand, a CD-ROM vendor could easily check the individual +package licenses of the packages in <em>non-free</em> and include as +many on the CD-ROMs as he's allowed to. (Since this varies greatly from +vendor to vendor, this job can't be done by the Debian developers.) + <p> +Note also that the term "section" is also used to refer to categories +which simplify the organization and browsing of available packages, e.g. +<em>admin</em>, <em>net</em>, <em>utils</em> etc. Once upon a time, these +sections (subsections, rather) existed in the form of subdirectories within +the Debian archive. Nowadays, these exist only in the "Section" header +fields of packages. + - <item> remove the package + <sect1>Architectures + <p> +In the first days, the Linux kernel was only available for the Intel +i386 (or greater) platforms, and so was Debian. But when Linux became +more and more popular, the kernel was ported to other architectures, +too. + <p> +The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola +680x0 (like Atari, Amiga and Macintoshes), MIPS, and PowerPC. The +Linux 2.2 kernel supports even more architectures, including ARM and +UltraSPARC. Since Linux supports these platforms, Debian decided that +it should, too. Therefore, Debian has ports underway; in fact, we +also have ports underway to non-Linux kernel. Aside from +<em>i386</em> (our name for Intel x86), there is <em>m68k</em>, +<em>alpha</em>, <em>powerpc</em>, <em>sparc</em>, <em>hurd-i386</em>, +<em>arm</em>, <em>ia64</em>, <em>hppa</em>, <em>s390</em>, <em>mips</em>, +<em>mipsel</em> and <em>sh</em> as of this writing. + <p> +&debian-formal; 1.3 is only available as <em>i386</em>. Debian 2.0 +shipped for <em>i386</em> and <em>m68k</em> architectures. Debian 2.1 +ships for the <em>i386</em>, <em>m68k</em>, <em>alpha</em>, and +<em>sparc</em> architectures. Debian 2.2 added support for the +<em>powerpc</em> and <em>arm</em> architectures. Debian 3.0 adds +support of five new architectures: <em>ia64</em>, <em>hppa</em>, +<em>s390</em>, <em>mips</em> and <em>mipsel</em>. + <p> +Information for developers or uses about the specific ports are +available at the <url id="&url-debian-ports;" name="Debian Ports web +pages">. - <item> run <prgn/lintian/ over the package. You can run - <prgn/lintian/ as follows: <tt>lintian -v - <var>package-NN</var>.changes</tt>. This will check the - source package as well as the binary package. If you - don't understand the output that <prgn/lintian/ - generates, try adding the <tt/-i/ switch, which will - cause <prgn/lintian/ to output a very verbose - description of the problem. - </list> + <sect1>Packages + <p> +There are two types of Debian packages, namely <em>source</em> and +<em>binary</em> packages. + <p> +Source packages consist of either two or three files: a <file>.dsc</file> +file, and either a <file>.tar.gz</file> file or both an +<file>.orig.tar.gz</file> and a <file>.diff.gz</file> file. + <p> +If a package is developed specially for Debian and is not distributed +outside of Debian, there is just one <file>.tar.gz</file> file which +contains the sources of the program. If a package is distributed +elsewhere too, the <file>.orig.tar.gz</file> file stores the so-called +<em>upstream source code</em>, that is the source code that's +distributed from the <em>upstream maintainer</em> (often the author of +the software). In this case, the <file>.diff.gz</file> contains the +changes made by the Debian maintainer. + <p> +The <file>.dsc</file> file lists all the files in the source package together +with checksums (<prgn>md5sums</prgn>) and some additional info about +the package (maintainer, version, etc.). - <sect1>Transferring the files to master - <p> -To upload a package, you need a personal account on -<ftpsite>master.debian.org</ftpsite>. All maintainers should already -have this account. You can use either <prgn/ssh/ or <prgn/ftp/ to -transfer the files. In either case, the files need to be placed into -<ftppath>/home/Debian/ftp/private/project/Incoming</ftppath>. (You -cannot upload to Incoming on master using anonymous FTP--you must use -your user-name and password.) - <p> -You may also find the Debian package <prgn/dupload/ useful when -uploading packages. This handy program is distributed with defaults -for uploading via <prgn/ftp/ to <tt/master/, <tt/chiark/, and -<tt/erlangen/. It can also be configured to use <prgn/ssh/. See -<manref name="dupload" section="1"> and <manref name="dupload" -section="5"> for more information. + <sect1>Distribution directories + <p> +The directory system described in the previous chapter is itself +contained within <em>distribution directories</em>. Each +distribution is actually contained in the <file>pool</file> directory in the +top-level of the Debian archive itself. + <p> +To summarize, the Debian archive has a root directory within an FTP +server. For instance, at the mirror site, +<ftpsite>ftp.us.debian.org</ftpsite>, the Debian archive itself is +contained in <ftppath>/debian</ftppath>, which is a common location +(another is <file>/pub/debian</file>). + <p> +A distribution is comprised of Debian source and binary packages, and the +respective <file>Sources</file> and <file>Packages</file> index files, containing +the header information from all those packages. The former are kept in the +<file>pool/</file> directory, while the latter are kept in the <file>dists/</file> +directory of the archive (for backwards compatibility). - <sect1>Uploads via Chiark - <p> -If you have a slow network connection to <tt/master/, there are two -alternatives: You can upload files to Incoming via a cron-driven -upload queue in Europe on <tt/chiark/. For details connect to -<ftpsite>ftp.chiark.greenend.org.uk</ftpsite> using anonymous FTP and -read -<ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>. - <p> -The program <tt/dupload/ supports uploads to chiark, please refer to -the documentation that comes with the program for details. + <sect2 id="sec-dists">Stable, testing, and unstable + <p> +There are always distributions called <em>stable</em> (residing in +<file>dists/stable</file>), one called <em>testing</em> (residing in +<file>dists/testing</file>), and one called <em>unstable</em> (residing in +<file>dists/unstable</file>). This reflects the development process of the +Debian project. + <p> +Active development is done in the <em>unstable</em> distribution +(that's why this distribution is sometimes called the <em>development +distribution</em>). Every Debian developer can update his or her +packages in this distribution at any time. Thus, the contents of this +distribution changes from day-to-day. Since no special effort is done +to make sure everything in this distribution is working properly, it is +sometimes literally unstable. + <p> +<ref id="testing"> is generated automatically by taking +packages from unstable if they satisfy certain criteria. Those +criteria should ensure a good quality for packages within testing. +The update to testing is launched each day after the +new packages have been installed. + <p> +After a period of development, once the release manager deems fit, the +<em>testing</em> distribution is frozen, meaning that the policies +which control how packages move from <em>unstable</em> to <em>testing</em> are +tightened. Packages which are too buggy are removed. No changes are +allowed into <em>testing</em> except for bug fixes. After some time +has elapsed, depending on progress, the <em>testing</em> distribution +goes into a `deep freeze', when no changes are made to it except those +needed for the installation system. This is called a “test cycle”, +and it can last up to two weeks. There can be several test cycles, +until the distribution is prepared for release, as decided by the +release manager. At the end of the last test cycle, the +<em>testing</em> distribution is renamed to <em>stable</em>, +overriding the old <em>stable</em> distribution, which is removed at +that time (although it can be found at <tt>&archive-host;</tt>). + <p> +This development cycle is based on the assumption that the +<em>unstable</em> distribution becomes <em>stable</em> after passing a +period of being in <em>testing</em>. Even once a distribution is +considered stable, a few bugs inevitably remain — that's why the +stable distribution is updated every now and then. However, these +updates are tested very carefully and have to be introduced into the +archive individually to reduce the risk of introducing new bugs. You +can find proposed additions to <em>stable</em> in the +<file>proposed-updates</file> directory. Those packages in +<file>proposed-updates</file> that pass muster are periodically moved as a +batch into the stable distribution and the revision level of the +stable distribution is incremented (e.g., ‘3.0’ becomes +‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and +so forth). + <p> +Note that development under <em>unstable</em> continues during the +freeze period, since the <em>unstable</em> distribution remains in +place in parallel with <em>testing</em>. - <sect1>Uploads via Erlangen + <sect2 id="experimental">Experimental <p> -Another cron-driven upload queue is available in Germany: just upload -the files via anonymous FTP to <url -id="ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue">. +The <em>experimental</em> distribution is a special distribution. +It is not a full distribution in the same sense as `stable' and +`unstable' are. Instead, it is meant to be a temporary staging area +for highly experimental software where there's a good chance that the +software could break your system, or software that's just too unstable +even for the <em>unstable</em> distribution (but there is a reason to +package it nevertheless). Users who download and install +packages from <em>experimental</em> are expected to have been duly +warned. In short, all bets are off for the <em>experimental</em> +distribution. <p> -The upload must be a complete Debian upload, as you would put it into -master's <tt/Incoming/, i.e., a <tt/.changes/ files along with the -other files mentioned in the <tt/.changes/. The queue daemon also -checks that the <tt/.changes/ is correctly PGP-signed by a Debian -developer, so that no bogus files can find their way to master via the -queue. Please also make sure that the <tt/Maintainer:/ field in the -<tt/.changes/ contains <em/your/ e-mail address. The address found -there is used for all replies, just as on master. +These are the <manref name="sources.list" section="5"> lines for +<em>experimental</em>: +<example> +deb http://ftp.<var>xy</var>.debian.org/debian/ ../project/experimental main +deb-src http://ftp.<var>xy</var>.debian.org/debian/ ../project/experimental main +</example> <p> -There's no need to move your files into a second directory after the -upload as on chiark. And, in any case, you should get some mail reply -from the queue daemon what happened to your upload. Hopefully it -should have been moved to master, but in case of errors you're -notified, too. +If there is a chance that the software could do grave damage to a system, +it is likely to be better to put it into <em>experimental</em>. +For instance, an experimental compressed file system should probably go +into <em>experimental</em>. <p> -The program <prgn/dupload/ supports uploads to erlangen, please refer -to the documentation that comes with the program for details. - - - <sect1>Uploading to the non-us server +Whenever there is a new upstream version of a package that introduces new +features but breaks a lot of old ones, it should either not be uploaded, or +be uploaded to <em>experimental</em>. A new, beta, version of some software +which uses completely different configuration can go into +<em>experimental</em>, at the maintainer's discretion. If you are working +on an incompatible or complex upgrade situation, you can also use +<em>experimental</em> as a staging area, so that testers can get early +access. + <p> +Some experimental software can still go into <em>unstable</em>, with a few +warnings in the description, but that isn't recommended because packages +from <em>unstable</em> are expected to propagate to <em>testing</em> and +thus to <em>stable</em>. You should not be afraid to use +<em>experimental</em> since it does not cause any pain to the ftpmasters, +the experimental packages are automatically removed once you upload +the package in <em>unstable</em> with a higher version number. + <p> +New software which isn't likely to damage your system can go directly into +<em>unstable</em>. <p> -To upload a package to the <em/non-us/ server you just have to -transfer the files via anonymous ftp to <url -id="ftp://nonus.debian.org/pub/debian-non-US/Incoming">. Note, that -the <tt>.changes</tt> file must have a valid PGP signature from one of -the keys of the developers keyring. +An alternative to <em>experimental</em> is to use your personal web space +on <tt>people.debian.org</tt>. - <sect>Announcing package uploads + <sect1 id="codenames">Release code names <p> -When a package is uploaded an announcement should be posted to one of -the debian-changes lists. The announcement should give the (source) -package name and version number, and a very short summary of the -changes, in the <tt/Subject/ field, and should contain the PGP-signed -<tt/.changes/ file. Some additional explanatory text may be added -before the start of the <tt/.changes/ file. +Every released Debian distribution has a <em>code name</em>: Debian +1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0, +`hamm'; Debian 2.1, `slink'; Debian 2.2, `potato'; and Debian 3.0, `woody'. There is also +a ``pseudo-distribution'', called `sid', which is the current +`unstable' distribution; since packages are moved from `unstable' to +`testing' as they approach stability, `sid' itself is never released. +As well as the usual contents of a Debian distribution, `sid' contains +packages for architectures which are not yet officially supported or +released by Debian. These architectures are planned to be integrated +into the mainstream distribution at some future date. <p> -If a package is released with the <tt/Distribution:/ set to -<tt/stable/, the announcement is sent to -<email/debian-changes@lists.debian.org/. +Since Debian has an open development model (i.e., everyone can +participate and follow the development) even the `unstable' and `testing' +distributions are distributed to the Internet through the Debian FTP and +HTTP server network. Thus, if we had called the directory which contains +the release candidate version `testing', then we would have to rename it +to `stable' when the version is released, which would cause all FTP +mirrors to re-retrieve the whole distribution (which is quite large). <p> -If a package is released with <tt/Distribution:/ set to <tt/unstable/, -<tt/experimental/, or <tt/frozen/ (when present), the announcement -should be posted to <email/debian-devel-changes@lists.debian.org/ -instead. +On the other hand, if we called the distribution directories +<em>Debian-x.y</em> from the beginning, people would think that Debian +release <em>x.y</em> is available. (This happened in the past, where a +CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development +version. That's the reason why the first official Debian release was +1.1, and not 1.0.) <p> -If you use dupload, it is clever enough to determine for itself where -the announcement should go, and will automatically mail the -announcement. +Thus, the names of the distribution directories in the archive are +determined by their code names and not their release status (e.g., +`slink'). These names stay the same during the development period and +after the release; symbolic links, which can be changed easily, +indicate the currently released stable distribution. That's why the +real distribution directories use the <em>code names</em>, while +symbolic links for <em>stable</em>, <em>testing</em>, and +<em>unstable</em> point to the appropriate release directories. + - <sect>Notification that a new package has been installed + <sect id="mirrors">Debian mirrors <p> -The Debian archive maintainers are responsible for handling package -uploads. For the most part, uploads are automatically handled on a -daily basis by an archive maintenance tool called <prgn/dinstall/. -Specifically, updates to existing packages to the `unstable' -distribution are handled automatically. In other cases, notably new -packages, placing the uploaded package into the distribution is -handled manually. When uploads are handled manually, the change to the -archive may take up to a week to occur (please be patient). - <p> -In any case, you will receive notification indicating that the package -has been uploaded via email. Please examine this notification -carefully. Sometimes the "override" file which the archive -maintainers use to indicate where packages go, is incorrect or -out-of-sync with your control file. In these cases, you should either -correct your control file or file a bug against <tt/ftp.debian.org/ -using the BTS. - - <sect>Interim releases +The various download archives and the web site have several mirrors +available in order to relieve our canonical servers from heavy load. +In fact, some of the canonical servers aren't public, and instead a +first tier of mirrors balances the load. That way, users always access +the mirrors and get used to using them, which allows Debian to better +spread its bandwidth requirements over several servers and networks, +and basically makes users avoid hammering on one primary location. +Note that the first tier of mirrors is as up-to-date as it can be since +they update when triggered from the internal sites (we call this +"push mirroring"). <p> -Under certain circumstances it is necessary for someone other than the -usual package maintainer to make a release of a package. For example, -a porter for another architecture may have to make some small changes -to the source package and does not wish to wait with uploading their -release until the main maintainer has incorporated the patch, or a -serious security problem or bug may have come to light requiring -immediate attention. - <p> -When a security bug is detected a fixed package should be uploaded as -soon as possible. In this case, the Debian Security Managers should -get in contact with the package maintainer to make sure a fixed -package is uploaded within a reasonable time (less than 48 hours). If -the package maintainer cannot provide a fixed package fast enough or -if he/she cannot be reached in time, the Security Manager may upload a -fixed package. - <p> -When someone other than the usual maintainer releases a package they -should add a new component to the <var/debian-revision/ component of -the version number--that is, the portion after the (last) hyphen. -This extra component will start at <tt/1/. This is to avoid -`stealing' one of the usual maintainer's version numbers, possibly -disrupting their work. If there is no <var/debian-revision/ component -in the version number then one should be created, starting at <tt/1/. - <p> -If it is absolutely necessary for someone other than the usual -maintainer to make a release based on a new upstream version then the -person making the release should start with the <var/debian-revision/ -value <tt/0.1/. The usual maintainer of a package should start their -<var/debian-revision/ numbering at <tt/1/. - <p> -Maintainers other than the usual package maintainer should make as few -changes to the package as possible, and they should always send a -unified context diff (<tt/diff -u/) detailing their changes to the bug -tracking system properly flagged with the correct package so that the -usual maintainer is kept aware of the situation. - <p> -If the non-maintainer upload (as known as an "NMU") fixes some -existing bugs, the bug reports should not be closed. Technically, -only the official package maintainer or the original bug submitter are -allowed to close bugs. However, the person making the non-maintainer -release should send a short message to the bug tracking system to all -the fixed bugs explaining that they have been fixed. Using -<email/control@bugs.debian.org/, the party doing the NMU should also -set the severity of the bugs fixed in the NMU to "fixed". This -ensures that everyone knows that the bug was fixed in an NMU; however -the bug is left open until the changes in the NMU are incorporated -"officially" into the package by the offical package maintainer. - - <p> -The normal maintainer should do at least one of - <list compact> - <item> -apply the diff, - <item> -read the diff and decide on each part of it themselves, or - <item> -if the maintainer decides not to apply the patch but to release a new -version, read the description of the changes to the next upstream -version and ensure that they fix each problem that was fixed in the -non-maintainer release. - </list> +All the information on Debian mirrors, including a list of the available +public FTP/HTTP servers, can be found at <url id="&url-debian-mirrors;">. +This useful page also includes information and tools which can be helpful if +you are interested in setting up your own mirror, either for internal or +public access. <p> -In addition, the normal maintainer should <em/always/ include an entry -in the changelog file documenting the non-maintainer upload. +Note that mirrors are generally run by third-parties who are +interested in helping Debian. As such, developers generally do not +have accounts on these machines. - <sect>Maintainer changes + <sect id="incoming-system"> + <heading>The Incoming system <p> -Periodically, a listing of packages in need of new maintainers will be -sent to <email/debian-devel@lists.debian.org</email> list. This list -is also available at in the Work-Needing and Prospective Packages -document (WNPP), <url -id="ftp://ftp.debian.org/debian/doc/package-developer/prospective-packages.html"> -and at <url -id="http://www.debian.org/doc/prospective-packages.html">. If you wish -to take over maintenance of any of the packages listed in the WNPP, or -if you can no longer maintain a packages you have, or you simply want -to know if any one is working on a new package, send a message to -<email/wnpp@debian.org/. +The Incoming system is responsible of collecting updated packages and +installing them in the Debian archive. It consists of a set of +directories and scripts that are installed both on <tt>&ftp-master-host;</tt> +and <tt>&non-us-host;</tt>. <p> -If you take over an old package, you probably want to be listed as the -package's official maintainer in the bug system. This will happen -automatically once you upload a new version with an updated -<tt/Maintainer:/ field. If you do not expect to upload a new version -for a while, send an email to <email/override-change@debian.org/ so -that bug reports will go to you. - - - <chapt>Moving, removing, renaming, and orphaning packages - <p> -Some archive manipulation operation are not automated in the Debian -upload process. This chapter gives guidelines in what to do in these -cases. - - <sect>Moving packages +Packages are uploaded by all the maintainers into a directory called +<file>unchecked</file>. This directory is scanned every 15 minutes by +the <prgn>katie</prgn> script, which verifies the integrity of the uploaded packages and the cryptographic +signatures. If the package is considered ready to be installed, it +is moved into the <file>accepted</file> directory. If this is the first upload of +the package, it is moved in the <file>new</file> directory, where it waits +for an approval of the ftpmasters. If the package contains files to be installed +"by-hand" it is moved in the <file>byhand</file> directory, where it waits +for a manual installation by the ftpmasters. Otherwise, if any error has been detected, +the package is refused and is moved in the <file>reject</file> directory. <p> -Sometimes a package will change either it's section or it's -subsection. For instance, a package from the `non-free' section might -be GPL'd in a later version; in this case you should consider moving -it to `main' or `contrib' (see the <em/Policy Manual/ for guidelines). +Once the package is accepted the system sends a confirmation +mail to the maintainer, closes all the bugs marked as fixed by the upload +and the auto-builders may start recompiling it. The package is now publicly +accessible at <url id="&url-incoming;"> (there is no +such URL for packages in the non-US archive) until it is really installed +in the Debian archive. This happens only once a day, the package +is then removed from incoming and installed in the pool along with all +the other packages. Once all the other updates (generating new +<file>Packages</file> and <file>Sources</file> index files for example) have been +made, a special script is called to ask all the primary mirrors to update +themselves. <p> -In this case, it is sufficient to edit the package control information -normally and re-upload the package (see the <em/Packaging Manual/ for -details). Carefully examine the installation log sent to you when the -package is installed into the archive. If for some reason the old -location of the package remains, file a bug against -<prgn/ftp.debian.org/ asking that the old location be removed. Give -details on what you did, since it might be a <prgn/dinstall/ bug. +The archive maintenance software will also send the OpenPGP/GnuPG signed +<file>.changes</file> file that you uploaded to the appropriate mailing +lists. If a package is released with the <tt>Distribution:</tt> set to +`stable', the announcement is sent to &email-debian-changes;. +If a package is released with <tt>Distribution:</tt> set to `unstable' +or `experimental', the announcement will be posted to +&email-debian-devel-changes; instead. + <p> +All Debian developers have write access to the <file>unchecked</file> +directory in order to upload their packages, they also have that access +to the <file>reject</file> directory in order to remove their bad uploads +or to move some files back in the <file>unchecked</file> directory. But +all the other directories are only writable by the ftpmasters, that is +why you can not remove an upload once it has been accepted. - <sect>Removing packages + <sect1 id="delayed-incoming">Delayed incoming <p> -If for some reason you want to completely remove a package (say, if it -is an old compatability library which is not longer required), you -need to file a bug against <prgn/ftp.debian.org/ asking that the -package be removed. Make sure you indicate which distribution the -package should be removed from. +The <file>unchecked</file> directory has a special <file>DELAYED</file> +subdirectory. It is itself subdivided in nine directories +called <file>1-day</file> to <file>9-day</file>. Packages which are uploaded in +one of those directories will be moved in the real unchecked +directory after the corresponding number of days. +This is done by a script that is run each day and which moves the +packages between the directories. Those which are in "1-day" are +installed in <file>unchecked</file> while the others are moved in the +adjacent directory (for example, a package in <file>5-day</file> will +be moved in <file>4-day</file>). This feature is particularly useful +for people who are doing non-maintainer uploads. Instead of +waiting before uploading a NMU, it is uploaded as soon as it is +ready but in one of those <file>DELAYED/<var>x</var>-day</file> directories. +That leaves the corresponding number of days for the maintainer +to react and upload another fix themselves if they are not +completely satisfied with the NMU. Alternatively they can remove +the NMU. <p> -If in doubt concerning whether a package is disposable, email -<email/debian-devel@lists.debian.org/ asking for opinions. +The use of that delayed feature can be simplified with a bit +of integration with your upload tool. For instance, if you use +<prgn>dupload</prgn> (see <ref id="dupload">), you can add this +snippet to your configuration file: +<example> +$delay = ($ENV{DELAY} || 7); +$cfg{'delayed'} = { + fqdn => "&ftp-master-host;", + login => "yourdebianlogin", + incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/", + dinstall_runs => 1, + method => "scpb" +}; +</example> +Once you've made that change, <prgn>dupload</prgn> can be used to +easily upload a package in one of the delayed directories: +<example>DELAY=5 dupload --to delayed <changes-file></example> - <sect>Replacing or renaming packages - <p> -Sometimes you made a mistake naming the package and you need to rename -it. In this case, you need to follow a two-step process. First, set -your <tt>debian/control</tt> file to replace and conflict with the -obsolete name of the package (see the <em/Packaging Manual/ for -details). Once you've uploaded that package, and the package has -moved into the archive, file a bug against <prgn/ftp.debian.org/ -asking to remove the package with the obsolete name. - <sect>Orphaning a package + <sect id="testing"> + <heading>The "testing" distribution</heading> + <p> +The scripts that update the <em>testing</em> distribution are run each day +after the installation of the +updated packages. They generate the <file>Packages</file> files for +the <em>testing</em> distribution, but they do so in an intelligent manner +trying to avoid any inconsistency and trying to use only +non-buggy packages. + <p>The inclusion of a package from <em>unstable</em> is conditional on the following: +<list> + <item> +The package must have been available in <em>unstable</em> for several days; +the precise number depends on the upload's urgency field. It +is 10 days for low urgency, 5 days for medium urgency and 2 days for high +urgency. Those delays may be doubled during a freeze; + <item> +It must have less release-critical bugs than the version available +in <em>testing</em>; + <item> +It must be available on all architectures on which it has been +previously built. <ref id="madison"> may be of interest to +check that information; + <item> +It must not break any dependency of a package that is already available +in <em>testing</em>; + <item> +The packages on which it depends must either be available in <em>testing</em> +or they must be accepted into <em>testing</em> at the same time (and they will +if they respect themselves all the criteria); +</list> + <p> +To find out whether a package is progressing into testing or not, see the +testing script output on the <url name="web page of the testing distribution" +id="&url-testing-maint;">, or use the program <prgn>grep-excuses</prgn> +which is in the <package>devscripts</package> package. This utility can +easily be used in a <manref name="crontab" section="5"> to keep one +informed of the progression of their packages into <em>testing</em>. + <p> +The <file>update_excuses</file> file does not always give the precise reason +why the package is refused, one may have to find it on their own by looking +what would break with the inclusion of the package. The <url +id="&url-testing-maint;" name="testing web page"> gives some more information +about the usual problems which may be causing such troubles. + <p> +Sometimes, some packages never enter <em>testing</em> because the set of +inter-relationship is too complicated and can not be sorted out +by the scripts. In that case, the release manager must be +contacted, and he will force the inclusion of the packages. <p> -If you can no longer maintain a package, then you should set the -package maintainer to <tt>Debian QA -<debian-qa@lists.debian.org></tt> and email -<email/wnpp@debian.org/ indicating that the package is now orphaned. -If the package is especially crucial to Debian, you should instead -email <email/debian-devel@lists.debian.org/ asking for a new -maintainer. +In general, please refer to the <url name="testing web page" +id="&url-testing-maint;"> for more information. It also includes +answers to some of the frequently asked questions. - <chapt>Handling bug reports + <sect id="pkg-info">Package information + <p> - <sect>Monitoring bugs + <sect1 id="pkg-info-web">On the web <p> -If you want to be a good maintainer, you should periodically check the -<url id="http://www.debian.org/Bugs/" name="Debian bug tracking system -(BTS)"> for your packages. The BTS contains all the open bugs against -your packages. +Each package has several dedicated web pages. +<tt>http://&packages-host;/<var>package-name</var></tt> +displays each version of the package +available in the various distributions. Each version links to a page +which provides information, including the package description, +the dependencies and package download links. <p> -Maintainers interact with the BTS via email addresses at -<tt/bugs.debian.org/. Documentation on available commands can be -found at <url id="http://www.debian.org/Bugs/">, or, if you have -installed the <prgn/debian-doc/ package, you can look at the local -files <tt>/usr/doc/debian/bug-*</tt>. - <p> -Often as a package maintainer, you find bugs in other packages or else -have bugs reported to your packages which need to be reassigned. The -BTS instructions can tell you how to do this. Make sure the bug is -not already filed against a package. Try to do a good job reporting a -bug and redirecting it to the proper location. For extra credit, you -can go through other packages, merging bugs which are reported more -than once, or setting bug severities to "fixed" when they have already -been fixed. Note that when you are neither the bug submitter nor the -package maintainer, you are not empowered to actually close the bug -(unless you secure permission from the maintainer). - - <sect>When bugs are closed by new uploads - <p> -If you fix a bug in your packages, it is your responsibility as the -package maintainer to close the bug when it has been fixed. However, -you should not close the bug until the package which fixes the bug has -been accepted into the Debian archive. Therefore, once you get -notification that your updated package has been installed into the -archive, you can and should close the bug in the BTS. +The bug tracking system track bugs for each package. You can +view the bugs of a given package at the URL +<tt>http://&bugs-host;/<var>package-name</var></tt>. + + <sect1 id="madison">The <prgn>madison</prgn> utility + <p> +<prgn>madison</prgn> is a command-line utility that is available +on both <tt>&ftp-master-host;</tt> and <tt>&non-us-host;</tt>. It +uses a single argument corresponding to a package name. In result +it displays which version of the package is available for each +architecture and distribution combination. An example will explain +it better. <p> -Again, see the BTS documentation for details on how to do this. -Often, it's sufficient to mail the <tt/.changes file to -<email/<var/XXX/-done@bugs.debian.org/, where <var/XXX/ is your bug -number. +<example> +$ madison libdbd-mysql-perl +libdbd-mysql-perl | 1.2202-4 | stable | source, alpha, arm, i386, m68k, powerpc, sparc +libdbd-mysql-perl | 1.2216-2 | testing | source, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc +libdbd-mysql-perl | 1.2216-2.0.1 | testing | alpha +libdbd-mysql-perl | 1.2219-1 | unstable | source, alpha, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc +</example> + <p> +In this example, you can see that the version in <em>unstable</em> differs from +the version in <em>testing</em> and that there has been a binary-only NMU of the +package for the alpha architecture. Each time the package has been +recompiled on most of the architectures. - <sect>Lintian reports + <sect id="pkg-tracking-system">The Package Tracking System + <p> +The Package Tracking System (PTS) is basically a tool to track by mail +the activity of a source package. You just have to subscribe +to a source package to start getting the mails related to it. +You get the same mails as the maintainer. Each mail +sent through the PTS is classified and associated to one of +the keyword listed below. This will let you select the mails that +you want to receive. <p> -You should periodically get the new <prgn/lintian/ from `unstable' and -check over all your packages. Alternatively you can check for you're -maintainer email address at <url id="http://www.debian.org/lintian/">. -That page, which is updated automatically, contains <prgn/lintian/ -reports against the latest version of the package (usually from -'unstable') using the latest <prgn/lintian/. +By default you will get: +<taglist> + <tag><tt>bts</tt> + <item> +All the bug reports and following discussions. + <tag><tt>bts-control</tt> + <item> +The control mails notifying a status change in one of the bugs. + + <tag><tt>upload-source</tt> + <item> +The confirmation mail from <prgn>katie</prgn> when an uploaded source +package is accepted. - <sect>Reporting lots of bugs at once - <p> -If you report more then 10 bugs on the same topic at once, it is -recommended that you send a message to -<email/debian-devel@lists.debian.org/ describing your intention before -submitting the report. This will allow other developers to verify that -the bug is a real problem. In addition, it will prevent the situation -where several maintainers start filing the same bug report -simultaneously. + <tag><tt>katie-other</tt> + <item> +Other warning and error mails from <prgn>katie</prgn> (like the +override disparity for the section or priority field). + + <tag><tt>default</tt> + <item> +Any non-automatic mail sent to the PTS by people who wanted to +contact the subscribers of the package. This can be done by sending mail +to <tt><var>srcpackage</var>@&pts-host;</tt>. In order to prevent spam, +mails sent to these addresses must contain the header "X-PTS-Approved" +with a non-empty string. + + + <tag><tt>summary</tt> + <item> +In the future, you may receive regular summary mails to keep you +informed of the package's status (bug statistics, porting overview, +progression in <em>testing</em>, ...). +</taglist> <p> -Note, that when sending lots of bugs on the same subject, you should -send the bug report to <email/maintonly@bugs.debian.org/ so that the -bug report is not forwarded to the bug distribution mailing list. +You can also decide to receive some more information: +<taglist> + <tag><tt>upload-binary</tt> + <item> +The confirmation mail from <prgn>katie</prgn> when an uploaded binary +package is accepted (to check that your package is recompiled for all +architectures). + + <tag><tt>cvs</tt> + <item> +CVS commits if the maintainer has setup a system to forward commit +notification to the PTS. + + <tag><tt>ddtp</tt> + <item> +Translations of descriptions or debconf templates +submitted to the Debian Description Translation Project. +</taglist> + + <sect1 id="pts-commands">The PTS email interface + <p> +You can control your subscription(s) to the PTS by sending +various commands to <email>pts@qa.debian.org</email>. + +<taglist> + +<tag><tt>subscribe <srcpackage> [<email>]</tt> +<item> + Subscribes <var>email</var> to communications related to the source package + <var>srcpackage</var>. Sender address is used if the second argument is + not present. If <var>srcpackage</var> is not a valid source package, + you'll get a warning. However if it's a valid binary package, the PTS + will subscribe you to the corresponding source package. + +<tag><tt>unsubscribe <srcpackage> [<email>]</tt> +<item> + Removes a previous subscription to the source package <var>srcpackage</var> + using the specified email address or the sender address if the second + argument is left out. + +<tag><tt>which [<email>]</tt> +<item> + Lists all subscriptions for the sender or the email address optionally + specified. + +<tag><tt>keyword [<email>]</tt> +<item> + Tells you the keywords that you are accepting. Each mail sent through + the Package Tracking System is associated to a keyword and you receive + only the mails associated to keywords that you are accepting. Here is + the list of available keywords: + <list> + <item><tt>bts</tt>: mails coming from the Debian Bug Tracking System + <item><tt>bts-control</tt>: reply to mails sent to &email-bts-control; + <item><tt>summary</tt>: automatic summary mails about the state of a package + <item><tt>cvs</tt>: notification of CVS commits + <item><tt>ddtp</tt>: translations of descriptions and debconf templates + <item><tt>upload-source</tt>: announce of a new source upload that + has been accepted + <item><tt>upload-binary</tt>: announce of a new binary-only upload (porting) + <item><tt>katie-other</tt>: other mails from ftpmasters + (override disparity, etc.) + <item><tt>default</tt>: all the other mails (those which aren't "automatic") + </list> + +<tag><tt>keyword <srcpackage> [<email>]</tt> +<item> + Same as previous item but for the given source package since + you may select a different set of keywords for each source package. + +<tag><tt>keyword [<email>] {+|-|=} <list of keywords></tt> +<item> + Accept (+) or refuse (-) mails associated to the given keyword(s). + Define the list (=) of accepted keywords. + +<tag><tt>keyword <srcpackage> [<email>] {+|-|=} <list of keywords></tt> +<item> + Same as previous item but overrides the keywords list for the + indicated source package. + +<tag><tt>quit | thanks | --</tt> +<item> + Stops processing commands. All following lines are ignored by + the bot. +</taglist> + + <sect1 id="pts-mail-filtering">Filtering PTS mails + <p> +Once you are subscribed to a package, you will get the mails sent to +<tt><var>srcpackage</var>@packages.qa.debian.org</tt>. Those mails +have special headers appended to let you filter them in a special +mailbox with <prgn>procmail</prgn>. The added headers are +<tt>X-Loop</tt>, <tt>X-PTS-Package</tt>, <tt>X-PTS-Keyword</tt> and +<tt>X-Unsubscribe</tt>. + <p> +Here is an example of added headers for a source upload notification +on the <package>dpkg</package> package: +<example> +X-Loop: dpkg@&pts-host; +X-PTS-Package: dpkg +X-PTS-Keyword: upload-source +X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org +</example> + + <sect1 id="pts-cvs-commit">Forwarding CVS commits in the PTS + <p> +If you use a publicly accessible CVS repository for maintaining +your Debian package you may want to forward the commit notification +to the PTS so that the subscribers (possible co-maintainers) can +closely follow the package's evolution. + <p> +It's very easy to setup. Once your CVS repository generates commit +notifications, you just have to make sure it sends a copy of those mails +to <tt><var>srcpackage</var>_cvs@&pts-host;</tt>. Only people who +accepts the <em>cvs</em> keyword will receive the notifications. + + <sect1 id="pts-web">The PTS web interface + <p> +The PTS has been extended with a web interface that puts together +many information about each source package. It features many useful +links (BTS, QA stats, contact information, DDTP translation status, +buildd logs) and gathers many more information from various places +(30 latest changelog entries, testing status, ...). It's a very useful +tool if you want to know what's going on with a specific source +package. Furthermore there's a form that let you easily subscribe to +the mail service offered by the PTS. + <p> +You can jump directly to the web page concerning a specific source package +with an url like <tt>http://&pts-host;/<var>srcpackage</var></tt>. Otherwise +you can go through the <url id="http://&pts-host;" name="main page">. + <p> +This web interface has been designed like a portal for the development of +packages: you can add custom content on the pages of your packages. You can +add "static information" (news item that are meant to stay available +indefinitely) and news items in the "latest news" section. + <p> +Static news can be used to indicate: +<list> +<item>the availability of a project hosted on alioth.debian.org for co-maintaining the package +<item>a link to the upstream website +<item>a link to the upstream bugtracker +<item>the existence of an IRC channel dedicated to the software +<item>any other available resource that could be useful in the maintenance of the package +</list> +Usual news item may be used to announce that: +<list> +<item>beta packages are available for test +<item>final packages are expected for next week +<item>the packaging is about to be redone from scratch +<item>backports are available +<item>the maintainer is on vacation (if he wishes to publish this information) +<item>a NMU is being worked on +<item>something important will affect the package +</list> + <p> +Both kind of news are generated in a similar manner: you just have to send a mail +either to <email>pts-static-news@qa.debian.org</email> or to +<email>pts-news@qa.debian.org</email>. The mail should indicate which package is +concerned by the news by giving the name of the source package in a +<tt>X-PTS-Package</tt> mail header or in a <tt>Package</tt> pseudo-header (like the +BTS reports). If an URL is available in the <tt>X-PTS-Url</tt> mail header or in +the <tt>Url</tt> pseudo-header, then the result is a link to that URL instead +of a complete news item. + <p> +Some examples of valid mails used to generate news item in the PTS are following. The first one +adds a link to the cvsweb interface of debian-cd in the "Static information" section. +<example> +From: Raphael Hertzog <hertzog@debian.org> +To: pts-static-news@qa.debian.org +Subject: Browse debian-cd CVS repository with cvsweb + +Package: debian-cd +Url: http://cvs.debian.org/debian-cd/ +</example> +The second one is an announce sent to a mailing list which is also sent +to the PTS so that it is published on the PTS web page of the package. Note the +use of the BCC field to avoid answers sent to the PTS by mistake ... +<example> +From: Raphael Hertzog <hertzog@debian.org> +To: debian-gtk-gnome@lists.debian.org +Bcc: pts-news@qa.debian.org +Subject: Galeon 2.0 backported for woody +X-PTS-Package: galeon + +Hello gnomers ! + +I'm glad to announce that galeon has been backported for woody. You'll find +everything here: +... +</example> + <p> +Think twice before adding a news to the PTS because you won't be able to +remove it later and you wan't be able to edit it either. The only thing that you +can do is send a second news that will deprecate the information contained in +the first news. + + <sect id="ddpo">Developer's packages overview + <p> +A QA (quality assurance) web portal is available at <url + id="&url-ddpo;"> which displays a table listing all the packages +of a single developer (including those where the party is listed as +a co-maintainer). The table gives a good summary about the developer's +packages: number of bugs by severity, list of available versions in each +distribution, testing status and much more including links to any other +useful information. + <p> +It is a good idea to look up your own data regularly so that +you don't forget any open bug, and so that you don't forget which +packages are under your responsibility. + + + <chapt id="pkgs">Managing Packages + <p> +This chapter contains information related to creating, uploading, +maintaining, and porting packages. + + + <sect id="newpackage">New packages + <p> +If you want to create a new package for the Debian distribution, you +should first check the <url id="&url-wnpp;" name="Work-Needing and +Prospective Packages (WNPP)"> list. Checking the WNPP list ensures that +no one is already working on packaging that software, and that effort is +not duplicated. Read the <url id="&url-wnpp;" name="WNPP web pages"> for +more information. + <p> +Assuming no one else is already working on your prospective package, +you must then submit a bug report (<ref id="submit-bug">) against the +pseudo-package <package>wnpp</package> +describing your plan to create a new package, including, but not +limiting yourself to, a description of the package, the license of the +prospective package and the current URL where it can be downloaded +from. + <p> +You should set the subject of the bug to ``ITP: <var>foo</var> +-- <var>short description</var>'', substituting the name of the new +package for <var>foo</var>. The severity of the bug report must be set +to <em>wishlist</em>. If you feel it's necessary, send a copy to +&email-debian-devel; by putting the address in the <tt>X-Debbugs-CC:</tt> header +of the message (no, don't use <tt>CC:</tt>, because that way the message's subject +won't indicate the bug number). + <p> +Please include a <tt>Closes: bug#<var>nnnnn</var></tt> entry on the +changelog of the new package in order for the bug report to be +automatically closed once the new package is installed on the archive +(<ref id="upload-bugfix">). + <p> +There are a number of reasons why we ask maintainers to announce their +intentions: + <list compact> + <item> +It helps the (potentially new) maintainer to tap into the experience +of people on the list, and lets them know if anyone else is working +on it already. + <item> +It lets other people thinking about working on the package know that +there already is a volunteer, so efforts may be shared. + <item> +It lets the rest of the maintainers know more about the package than +the one line description and the usual changelog entry ``Initial release'' +that gets posted to <tt>debian-devel-changes</tt>. + <item> +It is helpful to the people who live off unstable (and form our first +line of testers). We should encourage these people. + <item> +The announcements give maintainers and other interested parties a +better feel of what is going on, and what is new, in the project. + </list> + + + <sect id="changelog-entries">Recording changes in the package + <p> +Changes that you make to the package need to be recorded in the +<file>debian/changelog</file>. These changes should provide a concise +description of what was changed, why (if it's in doubt), and note if +any bugs were closed. They also record when the package was +completed. This file will be installed in +<file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>, or +<file>/usr/share/doc/<var>package</var>/changelog.gz</file> for native +packages. + <p> +The <file>debian/changelog</file> file conforms to a certain structure, +with a number of different fields. One field of note, the +<em>distribution</em>, is described in <ref id="distribution">. More +information about the structure of this file can be found in +the Debian Policy section titled "<file>debian/changelog</file>". + <p> +Changelog entries can be used to automatically close Debian bugs when +the package is installed into the archive. See <ref +id="upload-bugfix">. + <p> +It is conventional that the changelog entry notating of a package that +contains a new upstream version of the software looks like this: +<example> + * new upstream version +</example> + <p> +There are tools to help you create entries and finalize the +<file>changelog</file> for release — see <ref id="devscripts"> +and <ref id="dpkg-dev-el">. + <p> +See also <ref id="bpp-debian-changelog">. + + + <sect id="sanitycheck">Testing the package + <p> +Before you upload your package, you should do basic testing on it. At +a minimum, you should try the following activities (you'll need to +have an older version of the same Debian package around): +<list> + <item> +Install the package and make sure the software works, or upgrade the +package from an older version to your new version if a Debian package +for it already exists. + <item> +Run <prgn>lintian</prgn> over the package. You can run +<prgn>lintian</prgn> as follows: <tt>lintian -v +<var>package-version</var>.changes</tt>. This will check the source +package as well as the binary package. If you don't understand the +output that <prgn>lintian</prgn> generates, try adding the <tt>-i</tt> +switch, which will cause <prgn>lintian</prgn> to output a very verbose +description of the problem. + <p> +Normally, a package should <em>not</em> be uploaded if it causes lintian +to emit errors (they will start with <tt>E</tt>). + <p> +For more information on <prgn>lintian</prgn>, see <ref id="lintian">. + <item> +Optionally run <ref id="debdiff"> to analyze changes from an older version, +if one exists. + <item> +Downgrade the package to the previous version (if one exists) — this +tests the <file>postrm</file> and <file>prerm</file> scripts. + <item> +Remove the package, then reinstall it. + </list> + + + <sect id="sourcelayout">Layout of the source package + <p> +There are two types of Debian source packages: + <list> + <item>the so-called <em>native</em> packages, where there is no + distinction between the original sources and the patches + applied for Debian + <item>the (more common) packages where there's an original source + tarball file accompanied by another file that contains the + patches applied for Debian + </list> + <p> +For the native packages, the source package includes a Debian source control +file (<tt>.dsc</tt>) and the source tarball (<tt>.tar.gz</tt>). A source +package of a non-native package includes a Debian source control file, the +original source tarball (<tt>.orig.tar.gz</tt>) and the Debian patches +(<tt>.diff.gz</tt>). + <p> +Whether a package is native or not is determined when it is built by +<manref name="dpkg-buildpackage" section="1">. The rest of this section +relates only to non-native packages. + <p> +The first time a version is uploaded which corresponds to a particular +upstream version, the original source tar file should be uploaded and +included in the <file>.changes</file> file. Subsequently, this very same +tar file should be used to build the new diffs and <file>.dsc</file> +files, and will not need to be re-uploaded. + <p> +By default, <prgn>dpkg-genchanges</prgn> and +<prgn>dpkg-buildpackage</prgn> will include the original source tar +file if and only if the Debian revision part of the source version +number is 0 or 1, indicating a new upstream version. This behavior +may be modified by using <tt>-sa</tt> to always include it or +<tt>-sd</tt> to always leave it out. + <p> +If no original source is included in the upload, the original +source tar-file used by <prgn>dpkg-source</prgn> when constructing the +<file>.dsc</file> file and diff to be uploaded <em>must</em> be +byte-for-byte identical with the one already in the archive. + + + <sect id="distribution">Picking a distribution + <p> +Each upload needs to specify which distribution the package is intended +for. The package build process extracts this information from the first +line of the <file>debian/changelog</file> file and places it in the +<tt>Distribution</tt> field of the <tt>.changes</tt> file. + <p> +There are several possible values for this field: `stable', `unstable', +`testing-proposed-updates' and `experimental'. Normally, packages are +uploaded into <em>unstable</em>. + <p> +Actually, there are two other possible distributions: `stable-security' and +`testing-security', but read <ref id="bug-security"> for more information on +those. + <p> +It is technically possible to upload a package into several distributions +at the same time but it usually doesn't make sense to use that feature +because the dependencies of the package may vary with the distribution. +In particular, it never makes sense to combine the <em>experimental</em> +distribution with anything else (see <ref id="experimental">). + + <sect1 id="upload-stable">Uploads to <em>stable</em> + <p> +Uploading to <em>stable</em> means that the package will be placed into the +<file>stable-proposed-updates</file> directory of the Debian archive for further +testing before it is actually included in <em>stable</em>. + <p> +Extra care should be taken when uploading to <em>stable</em>. Basically, a +package should only be uploaded to stable if one of the following happens: +<list> + <item>a security problem (e.g. a Debian security advisory) + <item>a truly critical functionality problem + <item>the package becomes uninstallable + <item>a released architecture lacks the package +</list> + <p> +It is discouraged to change anything else in the package that isn't +important, because even trivial fixes can cause bugs later on. Uploading +new upstream versions to fix security problems is deprecated; applying the +specific patch from the new upstream version to the old one ("back-porting" +the patch) is the right thing to do in most cases. + <p> +Packages uploaded to <em>stable</em> need to be compiled on systems running +<em>stable</em>, so that their dependencies are limited to the libraries +(and other packages) available in <em>stable</em>; for example, a package +uploaded to <em>stable</em> that depends on a library package that only +exists in unstable will be rejected. Making changes to dependencies of other +packages (by messing with <tt>Provides</tt> or shlibs files), possibly making +those other packages uninstallable, is strongly discouraged. + <p> +The Release Team (which can be reached at &email-debian-release;) will +regularly evaluate the uploads in <em>stable-proposed-updates</em> and decide if +your package can be included in <em>stable</em>. Please be clear (and +verbose, if necessary) in your changelog entries for uploads to +<em>stable</em>, because otherwise the package won't be considered for +inclusion. + + <sect1 id="upload-t-p-u">Uploads to <em>testing-proposed-updates</em> + <p> +The testing distribution is fed with packages from unstable according to the rules +explained in <ref id="testing">. However, the release manager may stop the testing +scripts when he wants to freeze the distribution. In that case, you may want to +upload to <em>testing-proposed-updates</em> to provide fixed packages during the freeze. + <p> +Keep in mind that packages uploaded there are not automatically processed, they +have to go through the hands of the release manager. So you'd better have a good +reason to upload there. In order to know what a good reason is in the +release manager's eyes, you should read the instructions that he regularly +gives on &email-debian-devel-announce;. + <p> +You should not upload to <em>testing-proposed-updates</em> when you can update your +packages through <em>unstable</em>. If you can't (for example because you have a +newer development version in unstable), you may use it but it is recommended to ask +the authorization of the release manager before. + + + <sect id="upload">Uploading a package + + <sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt> + <p> +To upload a package, you need a personal account on +<ftpsite>&ftp-master-host;</ftpsite>, which you should have as an +official maintainer. If you use <prgn>scp</prgn> or <prgn>rsync</prgn> +to transfer the files, place them into &us-upload-dir;; +if you use anonymous FTP to upload, place them into +&upload-queue;. + <p> +Please note that you should transfer +the changes file last. Otherwise, your upload may be rejected because the +archive maintenance software will parse the changes file and see that not +all files have been uploaded. If you don't want to bother with transferring +the changes file last, you can simply copy your files to a temporary +directory on <tt>ftp-master</tt> and then move them to +&us-upload-dir;. + <p> +<em>Note:</em> Do not upload to <tt>ftp-master</tt> cryptographic +packages which belong to <em>contrib</em> or <em>non-free</em>. Uploads of +such software should go to <tt>non-us</tt> (see <ref +id="upload-non-us">). Furthermore packages containing code that is +patent-restricted by the United States government can not be uploaded to +<tt>ftp-master</tt>; depending on the case they may still be uploaded to +<file>non-US/non-free</file> (it's in non-free because of distribution issues +and not because of the license of the software). If you can't upload it to +<tt>ftp-master</tt>, then neither can you upload it to the overseas upload +queues on <tt>chiark</tt> or <tt>erlangen</tt>. If you are not sure +whether U.S. patent controls or cryptographic controls apply to your +package, post a message to &email-debian-devel; and ask. + <p> +You may also find the Debian packages <ref id="dupload"> or +<ref id="dput"> useful +when uploading packages. These handy programs help automate the +process of uploading packages into Debian. + <p> +After uploading your package, you can check how the archive +maintenance software will process it by running <prgn>dinstall</prgn> +on your changes file: +<example>dinstall -n foo.changes</example> + <p> +Note that <prgn>dput</prgn> can do this for you automatically. + + <sect1 id="upload-non-us">Uploading to <tt>non-US</tt> + <p> +As discussed above, export controlled software should not be uploaded +to <tt>ftp-master</tt>. Instead, upload the package to +<ftpsite>non-us.debian.org</ftpsite>, placing the files in +&non-us-upload-dir; (again, both <ref id="dupload"> and <ref +id="dput"> can do this for you if invoked properly). By default, +you can use the same account/password that works on +<tt>ftp-master</tt>. If you use anonymous FTP to upload, place the +files into &upload-queue;. + <p> +You can check your upload the same way it's done on <tt>ftp-master</tt>, +with: +<example>dinstall -n foo.changes</example> + <p> +Note that U.S. residents or citizens are subject to restrictions on +export of cryptographic software. As of this writing, U.S. citizens +are allowed to export some cryptographic software, subject to +notification rules by the U.S. Department of Commerce. However, this +restriction has been waived for software which is already available +outside the U.S. Therefore, any cryptographic software which belongs +in the <em>main</em> section of the Debian archive and does not depend +on any package outside of <em>main</em> (e.g., does not depend on +anything in <em>non-US/main</em>) can be uploaded to <tt>ftp-master</tt> +or its queues, described above. + <p> +Debian policy does not prevent upload to non-US by U.S. residents or +citizens, but care should be taken in doing so. It is recommended that +developers take all necessary steps to ensure that they are not +breaking current US law by doing an upload to non-US, <em>including +consulting a lawyer</em>. + <p> +For packages in <em>non-US/main</em>, <em>non-US/contrib</em>, +developers should at least follow the <url id="&url-u.s.-export;" +name="procedure outlined by the US Government">. Maintainers of +<em>non-US/non-free</em> packages should further consult the <url +id="&url-notification-of-export;" name="rules on notification of +export"> of non-free software. + <p> +This section is for information only and does not constitute legal +advice. Again, it is strongly recommended that U.S. citizens and +residents consult a lawyer before doing uploads to non-US. + + + <sect1>Uploads via <tt>chiark</tt> + <p> +If you have a slow network connection to <tt>ftp-master</tt>, there are +alternatives. One is to upload files to <file>Incoming</file> via a +upload queue in Europe on <tt>chiark</tt>. For details connect to +<url id="&url-chiark-readme;">. + <p> +<em>Note:</em> Do not upload packages containing software that is +export-controlled by the United States government to the queue on +<tt>chiark</tt>. Since this upload queue goes to <tt>ftp-master</tt>, the +prescription found in <ref id="upload-ftp-master"> applies here as well. + <p> +The program <prgn>dupload</prgn> comes with support for uploading to +<tt>chiark</tt>; please refer to the documentation that comes with the +program for details. + + + <sect1>Uploads via <tt>erlangen</tt> + <p> +Another upload queue is available in Germany: just upload the files +via anonymous FTP to <url id="&url-upload-erlangen;">. + <p> +The upload must be a complete Debian upload, as you would put it into +<tt>ftp-master</tt>'s <file>Incoming</file>, i.e., a <file>.changes</file> files +along with the other files mentioned in the <file>.changes</file>. The +queue daemon also checks that the <file>.changes</file> is correctly +signed with GnuPG or OpenPGP by a Debian developer, so that no bogus files can find +their way to <tt>ftp-master</tt> via this queue. Please also make sure that +the <tt>Maintainer</tt> field in the <file>.changes</file> contains +<em>your</em> e-mail address. The address found there is used for all +replies, just as on <tt>ftp-master</tt>. + <p> +There's no need to move your files into a second directory after the +upload, as on <tt>chiark</tt>. And, in any case, you should get a +mail reply from the queue daemon explaining what happened to your +upload. Hopefully it should have been moved to <tt>ftp-master</tt>, but in +case of errors you're notified, too. + <p> +<em>Note:</em> Do not upload packages containing software that is +export-controlled by the United States government to the queue on +<tt>erlangen</tt>. Since this upload queue goes to <tt>ftp-master</tt>, the +prescription found in <ref id="upload-ftp-master"> applies here as well. + <p> +The program <prgn>dupload</prgn> comes with support for uploading to +<tt>erlangen</tt>; please refer to the documentation that comes with +the program for details. + + + <sect1>Other upload queues + <p> +Another upload queue is available which is based in the US, and is a +good backup when there are problems reaching <tt>ftp-master</tt>. You can +upload files, just as in <tt>erlangen</tt>, to <url +id="&url-upload-samosa;">. + <p> +An upload queue is available in Japan: just upload the files via +anonymous FTP to <url id="&url-upload-jp;">. + + + <sect1 id="upload-notification"> + <heading>Notification that a new package has been installed</heading> + <p> +The Debian archive maintainers are responsible for handling package +uploads. For the most part, uploads are automatically handled on a +daily basis by the archive maintenance tools, <prgn>katie</prgn>. +Specifically, updates to existing packages to +the `unstable' distribution are handled automatically. In other cases, +notably new packages, placing the uploaded package into the +distribution is handled manually. When uploads are handled manually, +the change to the archive may take up to a month to occur. Please be +patient. + <p> +In any case, you will receive an email notification indicating that the +package has been added to the archive, which also indicates which bugs will +be closed by the upload. Please examine this notification carefully, +checking if any bugs you meant to close didn't get triggered. + <p> +The installation notification also includes information on what +section the package was inserted into. If there is a disparity, you +will receive a separate email notifying you of that. Read on below. + <p> +Note also that if you upload via queues, the queue daemon software will +also send you a notification by email. + + <sect id="override-file">Determining section and priority of a package + <p> +The <file>debian/control</file> file's <tt>Section</tt> and +<tt>Priority</tt> fields do not actually specify where the file will +be placed in the archive, nor its priority. In order to retain the +overall integrity of the archive, it is the archive maintainers who +have control over these fields. The values in the +<file>debian/control</file> file are actually just hints. + <p> +The archive maintainers keep track of the canonical sections and +priorities for packages in the <em>override file</em>. If there is a +disparity between the <em>override file</em> and the package's fields +as indicated in <file>debian/control</file>, then you will receive an +email noting the divergence when the package is installed into the +archive. You can either correct your <file>debian/control</file> file +for your next upload, or else you may wish to make a change in the +<em>override file</em>. + <p> +To alter the actual section that a package is put in, you need to +first make sure that the <file>debian/control</file> in your package +is accurate. Next, send an email &email-override; or submit a bug +against <package>ftp.debian.org</package> requesting that the section +or priority for your package be changed from the old section or +priority to the new one. Be sure to explain your reasoning. + <p> +For more information about <em>override files</em>, see <manref +name="dpkg-scanpackages" section="8"> and +<url id="&url-bts-devel;#maintincorrect">. + <p> +Note also that the term "section" is used for the separation of packages +according to their licensing, e.g. <em>main</em>, <em>contrib</em> and +<em>non-free</em>. This is described in another section, <ref id="archive">. + + + <sect id="bug-handling">Handling bugs + <p> +Every developer has to be able to work with the Debian <url name="bug +tracking system" id="&url-bts;">. This includes knowing how to file bug +reports properly (see <ref id="submit-bug">), how to update them and +reorder them, and how to process and close them. + <p> +The bug tracking system's features interesting to developers are described +in the <url id="&url-bts-devel;" name="BTS documentation for developers">. +This includes closing bugs, sending followup messages, assigning severities, +tags, marking bugs as forwarded and other issues. + <p> +Operations such as reassigning bugs to other packages, merging separate +bug reports about the same issue, or reopening bugs when they are +prematurely closed, are handled using the so-called control mail server. +All of the commands available in this server are described in the +<url id="&url-bts-control;" name="BTS control server documentation">. + + <sect1 id="bug-monitoring">Monitoring bugs + <p> +If you want to be a good maintainer, you should periodically check the +<url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your +packages. The BTS contains all the open bugs against your packages. +You can check them by browsing this page: +<tt>http://&bugs-host;/<var>yourlogin</var>@debian.org</tt>. + <p> +Maintainers interact with the BTS via email addresses at +<tt>&bugs-host;</tt>. Documentation on available commands can be +found at <url id="&url-bts;">, or, if you have installed the +<package>doc-debian</package> package, you can look at the local files +&file-bts-docs;. + <p> +Some find it useful to get periodic reports on open bugs. You can add +a cron job such as the following if you want to get a weekly email +outlining all the open bugs against your packages: +<example> +# ask for weekly reports of bugs in my packages +&cron-bug-report; +</example> +Replace <var>address</var> with your official Debian +maintainer address. + + <sect1 id="bug-answering">Responding to bugs + <p> +Make sure that any discussion you have about bugs are sent both to +the original submitter of the bug, and the bug itself (e.g., +<email>123@&bugs-host;</email>). If you're writing a new +mail and you don't remember the submitter email address, you can +use the <email>123-submitter@&bugs-host;</email> email to +contact the submitter <em>and</em> to record your mail within the +bug log (that means you don't need to send a copy of the mail to +<email>123@&bugs-host;</email>). + <p> +Once you've dealt with a bug report (e.g. fixed it), mark it as +<em>done</em> (close it) by sending an explanation message to +<email>123-done@&bugs-host;</email>. If you're fixing a bug by +changing and uploading the package, you can automate bug closing as +described in <ref id="upload-bugfix">. + <p> +You should <em>never</em> close bugs via the bug server <tt>close</tt> +command sent to &email-bts-control;. If you do so, the original +submitter will not receive any information about why the bug was +closed. + + <sect1 id="bug-housekeeping">Bug housekeeping + <p> +As a package maintainer, you will often find bugs in other packages or +have bugs reported against your packages which are actually bugs in +other packages. The bug tracking system's features interesting to developers +are described in the <url id="&url-bts-devel;" name="BTS documentation for +Debian developers">. Operations such as reassigning, merging, and tagging +bug reports are described in the <url id="&url-bts-control;" name="BTS +control server documentation">. This section contains +some guidelines for managing your own bugs, based on the collective +Debian developer experience. + <p> +Filing bugs for problems that you find in other packages is one of +the "civic obligations" of maintainership, see <ref id="submit-bug"> +for details. However, handling the bugs in your own packages is +even more important. + <p> +Here's a list of steps that you may follow to handle a bug report: +<enumlist> + <item> +Decide whether the report corresponds to a real bug or not. Sometimes +users are just calling a program in the wrong way because they haven't +read the documentation. If you diagnose this, just close the bug with +enough information to let the user correct his problem (give pointers +to the good documentation and so on). If the same report comes up +again and again you may ask yourself if the documentation is good +enough or if the program shouldn't detect its misuse in order to +give an informative error message. This is an issue that may need +to be brought to the upstream author. + <p> +If the bug submitter disagree with your decision to close the bug, +they may reopen it until you find an agreement on how to handle it. +If you don't find any, you may want to tag the bug <tt>wontfix</tt> +to let people know that the bug exists but that it won't be corrected. +If this situation is unacceptable, you (or the submitter) may want to +require a decision of the technical committee by reassigning the bug +to <package>tech-ctte</package> (you may use the clone command of +the BTS if you wish to keep it reported against your package). Before +doing so, please read the <url id="&url-tech-ctte;" name="recommended procedure">. + <item> +If the bug is real but it's caused by another package, just reassign +the bug the right package. If you don't know which package it should +be reassigned to, you may either ask for help on &email-debian-devel; or +reassign it to <package>debian-policy</package> to let them decide which +package is in fault. + <p> +Sometimes you also have to adjust the severity of the bug so that it +matches our definition of the severity. That's because people tend to +inflate the severity of bugs to make sure their bugs are fixed quickly. +Some bugs may even be dropped to wishlist severity when the requested +change is just cosmetic. + <item> +The bug submitter may have forgotten to provide some information, in that +case you have to ask him the information required. You may use the +<tt>moreinfo</tt> tag to mark the bug as such. Moreover if you can't +reproduce the bug, you tag it <tt>unreproducible</tt>. Anyone who +can reproduce the bug is then invited to provide more information +on how to reproduce it. After a few months, if this information has not +been sent by someone, the bug may be closed. + <item> +If the bug is related to the packaging, you just fix it. If you are not +able to fix it yourself, then tag the bug as <tt>help</tt>. You can +also ask for help on &email-debian-devel; or &email-debian-qa;. If it's an +upstream problem, you have to forward it to the upstream author. +Forwarding a bug is not enough, you have to check at each release if +the bug has been fixed or not. If it has, you just close it, otherwise +you have to remind the author about it. If you have the required skills +you can prepare a patch that fixes the bug and that you send at the +same time to the author. Make sure to send the patch in the BTS and to +tag the bug as <tt>patch</tt>. + <item> +If you have fixed a bug in your local copy, or if a fix has been +committed to the CVS repository, you may tag the bug as +<tt>pending</tt> to let people know that the bug is corrected and that +it will be closed with the next upload (add the <tt>closes:</tt> in +the <file>changelog</file>). This is particularly useful if you +are several developers working on the same package. + <item> +Once a corrected package is available in the <em>unstable</em> +distribution, you can close the bug. This can be done automatically, +read <ref id="upload-bugfix">. +</enumlist> + + <sect1 id="upload-bugfix">When bugs are closed by new uploads + <p> +As bugs and problems are fixed your packages, it is your +responsibility as the package maintainer to close the bug. However, +you should not close the bug until the package which fixes the bug has +been accepted into the Debian archive. Therefore, once you get +notification that your updated package has been installed into the +archive, you can and should close the bug in the BTS. + <p> +However, it's possible to avoid having to manually close bugs after the +upload — just list the fixed bugs in your <file>debian/changelog</file> +file, following a certain syntax, and the archive maintenance software +will close the bugs for you. For example: + +<example> +acme-cannon (3.1415) unstable; urgency=low + + * Frobbed with options (closes: Bug#98339) + * Added safety to prevent operator dismemberment, closes: bug#98765, + bug#98713, #98714. + * Added man page. Closes: #98725. +</example> + +Technically speaking, the following Perl regular expression describes +how bug closing changelogs are identified: +<example> + /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig +</example> + +We prefer the <tt>closes: #<var>XXX</var></tt> syntax, as it is the +most concise entry and the easiest to integrate with the text of the +<file>changelog</file>. + <p> +If you happen to mistype a bug number or forget a bug in the changelog +entries, don't hesitate to undo any damage the error caused. To reopen +wrongly closed bugs, send an <tt>reopen <var>XXX</var></tt> command to +the bug tracking system's control address, &email-bts-control;. To +close any remaining bugs that were fixed by your upload, email the +<file>.changes</file> file to <email>XXX-done@&bugs-host;</email>, +where <var>XXX</var> is your bug number. + <p> +Bear in mind that it is not obligatory to close bugs using the +changelog as described above. If you simply want to close bugs that +don't have anything to do with an upload you made, do it by emailing +an explanation to <email>XXX-done@&bugs-host;</email>. Do +<strong>not</strong> close bugs in the changelog entry of a version if +the changes in that version of the package doesn't have any bearing on +the bug. + <p> +For general information on how to write your changelog entries, see +<ref id="bpp-debian-changelog">. + + + <sect1 id="bug-security">Handling security-related bugs + <p> +Due to their sensitive nature, security-related bugs must be handled +carefully. The Debian Security Team exists to coordinate this +activity, keeping track of outstanding security problems, helping +maintainers with security problems or fix them themselves, sending +security advisories, and maintaining security.debian.org. + +<!-- information about the security database goes here once it's ready --> +<!-- (mdz) --> + + <sect2 id="bug-security-you">What to do when you learn of a + security problem + <p> +When you become aware of a security-related bug in a Debian package, +whether or not you are the maintainer, collect pertinent information +about the problem, and promptly contact the security team at +&email-security-team;. +Useful information includes, for example: + +<list compact> + <item>What versions of the package are known to be affected by the + bug. Check each version that is present in a supported Debian + release, as well as testing and unstable. + + <item>The nature of the fix, if any is available (patches are + especially helpful) + + <item>Any fixed packages that you have prepared yourself (send only + the <tt>.diff.gz</tt> and <tt>.dsc</tt> files) + + <item>Any information needed for the advisory (see <ref + id="bug-security-advisories">) + +</list> + + <sect2 id="bug-security-confidentiality">Confidentiality + <p> +Unlike most other activities within Debian, information about security +issues must sometimes be kept private for a time. Whether this is the +case depends on the nature of the problem and corresponding fix, and +whether it is already a matter of public knowledge. +<p> +There are a few ways a developer can learn of a security problem: + +<list compact> + <item>he notices it on a public forum (mailing list, web site, etc.) + <item>someone files a bug report + <item>someone informs him via private email +</list> + + In the first two cases, the information is public and it is important + to have a fix as soon as possible. In the last case, however, it + might not be public information. In that case there are a few + possible options for dealing with the problem: + +<list> + <item>if it is a trivial problem (like insecure temporary files) + there is no need to keep the problem a secret and a fix should be + made and released. + + <item>if the problem is severe (remotely exploitable, possibility to + gain root privileges) it is preferable to share the information with + other vendors and coordinate a release. The security team keeps + contacts with the various organizations and individuals and can take + care of that. +</list> + +<p> + In all cases if the person who reports the problem asks to not + disclose the information that should be respected, with the obvious + exception of informing the security team (make sure you tell the + security team that the information can not be disclosed). + +<p> +Please note that if secrecy is needed you can also not upload a fix to +unstable (or anywhere else), since the changelog and diff information +for unstable is public. + +<p> +There are two reasons for releasing information even though secrecy is +requested: the problem has been known for a while, or that the problem +or exploit has become public. + + <sect2 id="bug-security-advisories">Security Advisories + <p> +Security advisories are only issued for the current, released stable +distribution, not for testing or unstable. When released, advisories +are sent to the &email-debian-security-announce; +mailing list and posted on <url +id="&url-debian-security-advisories;" name="the security web page">. +Security advisories are written and posted by the security +team. However they certainly do not mind if a maintainer can supply +some of the information for them, or write part of the +text. Information that should be in an advisory includes: + +<list compact> + <item>A description of the problem and its scope, including: + <list> + <item>The type of problem (privilege escalation, denial of + service, etc.) + <item>How it can be exploited + <item>Whether it is remotely or locally exploitable + <item>How the problem was fixed + </list> + <item>Version numbers of affected packages + <item>Version numbers of fixed packages + <item>Information on where to obtain the updated packages + <item>References to upstream advisories, <url + id="http://cve.mitre.org" name="CVE"> identifiers, and any other + information useful in cross-referencing the vulnerability +</list> + + <sect2 id="bug-security-building"> + <heading>Preparing packages to address security issues</heading> + <p> +One way that you can assist the security team in their duties is to +provide fixed packages suitable for a security advisory for the stable +Debian release. + <p> + When an update is made to the stable release, care must be taken to + avoid changing system behavior or introducing new bugs. In order to + do this, make as few changes as possible to fix the bug. Users and + administrators rely on the exact behavior of a release once it is + made, so any change that is made might break someone's system. + This is especially true of libraries: make sure you never change the + API or ABI, no matter how small the change. +<p> +This means that moving to a new upstream version is not a good +solution. Instead, the relevant changes should be back-ported to the +version present in the current stable Debian release. Generally, +upstream maintainers are willing to help if needed. If not, the +Debian security team may be able to help. +<p> +In some cases, it is not possible to back-port a security fix, for +example when large amounts of source code need to be modified or +rewritten. If this happens, it may be necessary to move to a new +upstream version. However, you must always coordinate that with the +security team beforehand. +<p> +Related to this is another important guideline: always test your +changes. If you have an exploit available, try it and see if it +indeed succeeds on the unpatched package and fails on the fixed +package. Test other, normal actions as well, as sometimes a security +fix can break seemingly unrelated features in subtle ways. +<p> +Review and test your changes as much as possible. Check the +differences from the previous version repeatedly +(<prgn>interdiff</prgn> from the <package>patchutils</package> package +and <prgn>debdiff</prgn> from <package>devscripts</package> are useful +tools for this, see <ref id="debdiff">). +<p> +When packaging the fix, keep the following points in mind: + +<list> + <item>Make sure you target the right distribution in your + <file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for + testing this is <tt>testing-security</tt>, and for the previous + stable release, this is <tt>oldstable-security</tt>. Do not target + <var>distribution</var>-proposed-updates! + + <item>Make sure the version number is proper. It must be greater + than the current package, but less than package versions in later + distributions. If in doubt, test it with <tt>dpkg + --compare-versions</tt>. For <em>testing</em>, there must be + a higher version in <em>unstable</em>. If there is none yet (for example, + if <em>testing</em> and <em>unstable</em> have the same version) you must upload a + new version to unstable first. + + <item>Do not make source-only uploads if your package has any + binary-all packages (do not use the <tt>-S</tt> option to + <prgn>dpkg-buildpackage</prgn>). The <prgn>buildd</prgn> infrastructure will + not build those. This point applies to normal package uploads as + well. + + <item>If the upstream source has been uploaded to + security.debian.org before (by a previous security update), build + the upload without the upstream source (<tt>dpkg-buildpackage + -sd</tt>). Otherwise, build with full source + (<tt>dpkg-buildpackage -sa</tt>). + + <item>Be sure to use the exact same <file>*.orig.tar.gz</file> as used in the + normal archive, otherwise it is not possible to move the security + fix into the main archives later. + + <item>Be sure, when compiling a package, to compile on a clean + system which only has packages installed from the distribution you + are building for. If you do not have such a system yourself, you + can use a debian.org machine (see <ref id="server-machines">) + or setup a chroot (see <ref id="pbuilder"> and + <ref id="debootstrap">). +</list> + + <sect2 id="bug-security-upload">Uploading the fixed package +<p> +<em>DO NOT</em> upload a package to the security upload queue without +prior authorization from the security team. If the package does not +exactly meet the team's requirements, it will cause many problems and +delays in dealing with the unwanted upload. +<p> +<em>DO NOT</em> upload your fix to proposed-updates without +coordinating with the security team. Packages from +security.debian.org will be copied into the proposed-updates directory +automatically. If a package with the same or a higher version number +is already installed into the archive, the security update will be +rejected by the archive system. That way, the stable distribution +will end up without a security update for this package instead. +<p> +Once you have created and tested the new package and it has been +approved by the security team, it needs to be uploaded so that it can +be installed in the archives. For security uploads, the place to +upload to is +<tt>ftp://security.debian.org/pub/SecurityUploadQueue/</tt> . + +<p> +Once an upload to the security queue has been accepted, the package +will automatically be rebuilt for all architectures and stored for +verification by the security team. + +<p> +Uploads which are waiting for acceptance or verification are only +accessible by the security team. This is necessary since there might +be fixes for security problems that cannot be disclosed yet. + +<p> +If a member of the security team accepts a package, it will be +installed on security.debian.org as well as the proper +<var>distribution</var>-proposed-updates on ftp-master or in the non-US +archive. + + + <sect id="archive-manip"> + <heading>Moving, removing, renaming, adopting, and orphaning + packages</heading> + <p> +Some archive manipulation operations are not automated in the Debian +upload process. These procedures should be manually followed by +maintainers. This chapter gives guidelines in what to do in these +cases. + + <sect1 id="moving-pkgs">Moving packages + <p> +Sometimes a package will change its section. For instance, a +package from the `non-free' section might be GPL'd in a later version, +in which case, the package should be moved to `main' or +`contrib'.<footnote> See the <url id="&url-debian-policy;" +name="Debian Policy Manual"> for guidelines on what section a package +belongs in. + </footnote> + <p> +If you need to change the section for one of your packages, change the +package control information to place the package in the desired +section, and re-upload the package (see the <url id="&url-debian-policy;" +name="Debian Policy Manual"> for details). If your new section is +valid, it will be moved automatically. If it does not, then contact +the ftpmasters in order to understand what happened. + <p> +If, on the other hand, you need to change the <em>subsection</em> of +one of your packages (e.g., ``devel'', ``admin''), the procedure is +slightly different. Correct the subsection as found in the control +file of the package, and re-upload that. Also, you'll need to get the +override file updated, as described in <ref id="override-file">. + + + <sect1 id="removing-pkgs">Removing packages + <p> +If for some reason you want to completely remove a package (say, if it +is an old compatibility library which is no longer required), you +need to file a bug against <tt>ftp.debian.org</tt> asking that the +package be removed. Make sure you indicate which distribution the +package should be removed from. Normally, you can only have packages +removed from <em>unstable</em> and <em>experimental</em>. Packages +are not removed from <em>testing</em> directly. Rather, they will be +removed automatically after the package has been removed from +<em>unstable</em> and no package in <em>testing</em> depends on it. + <p> +You also have to detail the reasons justifying that request. This is to +avoid unwanted removals and to keep a trace of why a package has been +removed. For example, you can provide the name of the package that +supersedes the one to be removed. + <p> +Usually you only ask the removal of a package maintained by yourself. +If you want to remove another package, you have to get the approval +of its last maintainer. + <p> +If in doubt concerning whether a package is disposable, email +&email-debian-devel; asking for opinions. Also of interest is the +<prgn>apt-cache</prgn> program from the <package>apt</package> +package. When invoked as <tt>apt-cache showpkg +<var>package</var></tt>, the program will show details for +<var>package</var>, including reverse depends. + <p> +Once the package has been removed, the package's bugs should be handled. +They should either be reassigned to another package in the case where +the actual code has evolved into another package (e.g. <tt>libfoo12</tt> +was removed because <tt>libfoo13</tt> supersedes it) or closed if the +software is simply no more part of Debian. + + <sect2>Removing packages from <file>Incoming</file> + <p> +In the past, it was possible to remove packages from <file>incoming</file>. +However, with the introduction of the new incoming system, this is no longer +possible. Instead, you have to upload a new revision of your package with +a higher version as the package you want to replace. Both versions will be +installed in the archive but only the higher version will actually be +available in <em>unstable</em> since the previous version will immediately +be replaced by the higher. However, if you do proper testing of your +packages, the need to replace a package should not occur too often anyway. + + <sect1>Replacing or renaming packages + <p> +Sometimes you made a mistake naming the package and you need to rename +it. In this case, you need to follow a two-step process. First, set +your <file>debian/control</file> file to replace and conflict with the +obsolete name of the package (see the <url id="&url-debian-policy;" +name="Debian Policy Manual"> for details). Once you've uploaded +the package and the package has moved into the archive, file a bug +against <tt>ftp.debian.org</tt> asking to remove the package with the +obsolete name. Do not forget to properly reassign the package's bugs +at the same time. + <p> +At other times, you may make a mistake in constructing your package and +wish to replace it. The only way to do this is to increase the version +number and upload a new version. The old version will be expired in +the usual manner. Note that this applies to each part of your package, +including the sources: if you wish to replace the upstream source tarball +of your package, you will need to upload it with a different version. An +easy possibility is to replace <file>foo_1.00.orig.tar.gz</file> with +<file>foo_1.00+0.orig.tar.gz</file>. This restriction gives each file +on the ftp site a unique name, which helps to ensure consistency across the +mirror network. + + <sect1 id="orphaning">Orphaning a package + <p> +If you can no longer maintain a package, you need to inform the others +about that, and see that the package is marked as orphaned. +You should set the package maintainer to <tt>Debian QA Group +&orphan-address;</tt> and submit a bug report +against the pseudo package <package>wnpp</package>. The bug report should be +titled <tt>O: <var>package</var> -- <var>short description</var></tt> +indicating that the package is now orphaned. The severity of the bug +should be set to <em>normal</em>. If you feel it's necessary, send a copy +to &email-debian-devel; by putting the address in the X-Debbugs-CC: header +of the message (no, don't use CC:, because that way the message's subject +won't indicate the bug number). + <p> +If the package is especially crucial to Debian, you should instead submit +a bug against <package>wnpp</package> and title it <tt>RFA: <var>package</var> -- +<var>short description</var></tt> and set its severity to +<em>important</em>. <tt>RFA</tt> stands for <em>Request For Adoption</em>. +Definitely copy the message to debian-devel in this case, as described +above. + <p> +Read instructions on the <url id="&url-wnpp;" name="WNPP web pages"> +for more information. + + <sect1 id="adopting">Adopting a package + <p> +A list of packages in need of a new maintainer is available at in the +<url name="Work-Needing and Prospective Packages list (WNPP)" +id="&url-wnpp;">. If you wish to take over maintenance of any of the +packages listed in the WNPP, please take a look at the aforementioned +page for information and procedures. + <p> +It is not OK to simply take over a package that you feel is neglected +— that would be package hijacking. You can, of course, contact the +current maintainer and ask them if you may take over the package. +If you have reason to believe a maintainer has gone AWOL +(absent without leave), see <ref id="mia-qa">. + <p> +Generally, you may not take over the package without the assent of the +current maintainer. Even if they ignore you, that is still not grounds to +take over a package. Complaints about maintainers should be brought up on +the developers' mailing list. If the discussion doesn't end with a positive +conclusion, and the issue is of a technical nature, consider bringing it to +the attention of the technical committee (see the <url name="technical +committee web page" id="&url-tech-ctte;"> for more information). + <p> +If you take over an old package, you probably want to be listed as the +package's official maintainer in the bug system. This will happen +automatically once you upload a new version with an updated +<tt>Maintainer:</tt> field, although it can take a few hours after the +upload is done. If you do not expect to upload a new version for a while, +you can use <ref id="pkg-tracking-system"> to get the bug reports. However, +make sure that the old maintainer has no problem with the fact that +they will continue to receive the bugs during that time. + + + <sect id="porting">Porting and being ported + <p> +Debian supports an ever-increasing number of architectures. Even if +you are not a porter, and you don't use any architecture but one, it +is part of your duty as a maintainer to be aware of issues of +portability. Therefore, even if you are not a porter, you should read +most of this chapter. + <p> +Porting is the act of building Debian packages for architectures that +is different from the original architecture of the package +maintainer's binary package. It is a unique and essential activity. +In fact, porters do most of the actual compiling of Debian packages. +For instance, for a single <em>i386</em> binary package, there must be +a recompile for each architecture, which amounts to +&number-of-arches; more builds. + + + <sect1 id="kind-to-porters">Being kind to porters + <p> +Porters have a difficult and unique task, since they are required to +deal with a large volume of packages. Ideally, every source package +should build right out of the box. Unfortunately, this is often not +the case. This section contains a checklist of ``gotchas'' often +committed by Debian maintainers — common problems which often stymie +porters, and make their jobs unnecessarily difficult. + <p> +The first and most important watchword is to respond quickly to bug or +issues raised by porters. Please treat porters with courtesy, as if +they were in fact co-maintainers of your package (which in a way, they +are). Please be tolerant of succinct or even unclear bug reports, +doing your best to hunt down whatever the problem is. + <p> +By far, most of the problems encountered by porters are caused by +<em>packaging bugs</em> in the source packages. Here is a checklist +of things you should check or be aware of. + +<enumlist> + <item> +Make sure that your <tt>Build-Depends</tt> and +<tt>Build-Depends-Indep</tt> settings in <file>debian/control</file> +are set properly. The best way to validate this is to use the +<package>debootstrap</package> package to create an unstable chroot +environment (see <ref id="debootstrap">). +Within that chrooted environment, install the +<package>build-essential</package> package and any package +dependencies mentioned in <tt>Build-Depends</tt> and/or +<tt>Build-Depends-Indep</tt>. Finally, try building your package +within that chrooted environment. These steps can be automated +by the use of the <prgn>pbuilder</prgn> program which is provided by +the package of the same name (see <ref id="pbuilder">). + <p> +If you can't set up a proper chroot, <prgn>dpkg-depcheck</prgn> may be +of assistance (see <ref id="dpkg-depcheck">). + <p> +See the <url id="&url-debian-policy;" name="Debian Policy +Manual"> for instructions on setting build dependencies. + <item> +Don't set architecture to a value other than ``all'' or ``any'' unless +you really mean it. In too many cases, maintainers don't follow the +instructions in the <url id="&url-debian-policy;" name="Debian Policy +Manual">. Setting your architecture to ``i386'' is usually incorrect. + <item> +Make sure your source package is correct. Do <tt>dpkg-source -x +<var>package</var>.dsc</tt> to make sure your source package unpacks +properly. Then, in there, try building your package from scratch with +<prgn>dpkg-buildpackage</prgn>. + <item> +Make sure you don't ship your source package with the +<file>debian/files</file> or <file>debian/substvars</file> files. +They should be removed by the `clean' target of +<file>debian/rules</file>. + <item> +Make sure you don't rely on locally installed or hacked configurations +or programs. For instance, you should never be calling programs in +<file>/usr/local/bin</file> or the like. Try not to rely on programs +be setup in a special way. Try building your package on another +machine, even if it's the same architecture. + <item> +Don't depend on the package you're building already being installed (a +sub-case of the above issue). + <item> +Don't rely on the compiler being a certain version, if possible. If +not, then make sure your build dependencies reflect the restrictions, +although you are probably asking for trouble, since different +architectures sometimes standardize on different compilers. + <item> +Make sure your debian/rules contains separate ``binary-arch'' and +``binary-indep'' targets, as the Debian Policy Manual requires. +Make sure that both targets work independently, that is, that you can +call the target without having called the other before. To test this, +try to run <tt>dpkg-buildpackage -b</tt>. + </enumlist> + + + <sect1 id="porter-guidelines">Guidelines for porter uploads + <p> +If the package builds out of the box for the architecture to be ported +to, you are in luck and your job is easy. This section applies to +that case; it describes how to build and upload your binary package so +that it is properly installed into the archive. If you do have to +patch the package in order to get it to compile for the other +architecture, you are actually doing a source NMU, so consult <ref +id="nmu-guidelines"> instead. + <p> +For a porter upload, no changes are being made to the source. You do +not need to touch any of the files in the source package. This +includes <file>debian/changelog</file>. + <p> +The way to invoke <prgn>dpkg-buildpackage</prgn> is as +<tt>dpkg-buildpackage -B -m<var>porter-email</var></tt>. Of course, +set <var>porter-email</var> to your email address. This will do a +binary-only build of only the architecture-dependent portions of the +package, using the `binary-arch' target in <file>debian/rules</file>. + + <sect2 id="binary-only-nmu"> + <heading>Recompilation or binary-only NMU</heading> + <p> +Sometimes the initial porter upload is problematic because the environment +in which the package was built was not good enough (outdated or obsolete +library, bad compiler, ...). Then you may just need to recompile it in +an updated environment. However, you have to bump the version number in +this case, so that the old bad package can be replaced in the Debian archive +(<prgn>katie</prgn> refuses to install new packages if they don't have a +version number greater than the currently available one). Despite the +required modification of the changelog, these are called binary-only NMUs +— there is no need in this case to trigger all other architectures +to consider themselves out of date or requiring recompilation. + <p> +Such recompilations require special ``magic'' version numbering, so that +the archive maintenance tools recognize that, even though there is a +new Debian version, there is no corresponding source update. If you +get this wrong, the archive maintainers will reject your upload (due +to lack of corresponding source code). + <p> +The ``magic'' for a recompilation-only NMU is triggered by using the +third-level number on the Debian part of the version. For instance, +if the latest version you are recompiling against was version +``2.9-3'', your NMU should carry a version of ``2.9-3.0.1''. If the +latest version was ``3.4-2.1'', your NMU should have a version number +of ``3.4-2.1.1''. + + + <sect2 id="source-nmu-when-porter"> + <heading>When to do a source NMU if you are a porter</heading> + <p> +Porters doing a source NMU generally follow the guidelines found in +<ref id="nmu">, just like non-porters. However, it is expected that +the wait cycle for a porter's source NMU is smaller than for a +non-porter, since porters have to cope with a large quantity of +packages. +Again, the situation varies depending on the distribution they are +uploading to. + +<!-- +FIXME: commented out until I can work out how to upload to testing directly + + Crucial fixes (i.e., changes need to get a source +package to compile for a released-targeted architecture) can be +uploaded with <em>no</em> waiting period for the `frozen' distribution. + --> + <p> +However, if you are a porter doing an NMU for `unstable', the above +guidelines for porting should be followed, with two variations. +Firstly, the acceptable waiting period — the time between when the +bug is submitted to the BTS and when it is OK to do an NMU — is seven +days for porters working on the unstable distribution. This period +can be shortened if the problem is critical and imposes hardship on +the porting effort, at the discretion of the porter group. (Remember, +none of this is Policy, just mutually agreed upon guidelines.) + <p> +Secondly, porters doing source NMUs should make sure that the bug they +submit to the BTS should be of severity `serious' or greater. This +ensures that a single source package can be used to compile every +supported Debian architecture by release time. It is very important +that we have one version of the binary and source package for all +architecture in order to comply with many licenses. + <p> +Porters should try to avoid patches which simply kludge around bugs in +the current version of the compile environment, kernel, or libc. +Sometimes such kludges can't be helped. If you have to kludge around +compilers bugs and the like, make sure you <tt>#ifdef</tt> your work +properly; also, document your kludge so that people know to remove it +once the external problems have been fixed. + <p> +Porters may also have an unofficial location where they can put the +results of their work during the waiting period. This helps others +running the port have the benefit of the porter's work, even during +the waiting period. Of course, such locations have no official +blessing or status, so buyer, beware. + + + <sect1 id="porter-automation"> + <heading>Porting infrastructure and automation</heading> + <p> +There is infrastructure and several tools to help automate the package +porting. This section contains a brief overview of this automation and +porting to these tools; see the package documentation or references for +full information.</p> + + <sect2> + <heading>Mailing lists and web pages</heading> + <p> +Web pages containing the status of each port can be found at <url +id="&url-debian-ports;">. + <p> +Each port of Debian has a mailing list. The list of porting mailing +lists can be found at <url id="&url-debian-port-lists;">. These lists +are used to coordinate porters, and to connect the users of a given +port with the porters.</p> + </sect2> + + <sect2> + <heading>Porter tools</heading> + <p> +Descriptions of several porting tools can be found in <ref +id="tools-porting">.</p> + </sect2> + + <sect2 id="buildd"> + <heading><package>buildd</package></heading> + <p> +The <package>buildd</package> system is used as a distributed, +client-server build distribution system. It is usually used in +conjunction with <em>auto-builders</em>, which are ``slave'' hosts +which simply check out and attempt to auto-build packages which need +to be ported. There is also an email interface to the system, which +allows porters to ``check out'' a source package (usually one which +cannot yet be auto-built) and work on it. + <p> +<package>buildd</package> is not yet available as a package; however, +most porting efforts are either using it currently or planning to use +it in the near future. The actual automated builder is packaged as +<package>sbuild</package>, see its description in <ref id="sbuild">. +The complete <package>buildd</package> system also collects a number of as yet unpackaged +components which are currently very useful and in use continually, +such as <prgn>andrea</prgn> and +<prgn>wanna-build</prgn>. + <p> +Some of the data produced by <package>buildd</package> which is +generally useful to porters is available on the web at <url +id="&url-buildd;">. This data includes nightly updated information +from <prgn>andrea</prgn> (source dependencies) and +<package>quinn-diff</package> (packages needing recompilation). + <p> +We are quite proud of this system, since it has so +many possible uses. Independent development groups can use the system for +different sub-flavors of Debian, which may or may not really be of +general interest (for instance, a flavor of Debian built with <prgn>gcc</prgn> +bounds checking). It will also enable Debian to recompile entire +distributions quickly. + </sect2> + + + <sect id="nmu">Non-Maintainer Uploads (NMUs) + <p> +Under certain circumstances it is necessary for someone other than the +official package maintainer to make a release of a package. This is +called a non-maintainer upload, or NMU. + <p> +Debian porters, who compile packages for different architectures, +occasionally do binary-only NMUs as part of their porting activity +(see <ref id="porting">). Another reason why NMUs are done is when a +Debian developers needs to fix another developers' packages in order to +address serious security problems or crippling bugs, especially during +the freeze, or when the package maintainer is unable to release a fix +in a timely fashion. + <p> +This chapter contains information providing guidelines for when and +how NMUs should be done. A fundamental distinction is made between +source and binary-only NMUs, which is explained in the next section. + + <sect1 id="nmu-terms">Terminology + <p> +There are two new terms used throughout this section: ``binary-only NMU'' +and ``source NMU''. These terms are used with specific technical +meaning throughout this document. Both binary-only and source NMUs are +similar, since they involve an upload of a package by a developer who +is not the official maintainer of that package. That is why it's a +<em>non-maintainer</em> upload. + <p> +A source NMU is an upload of a package by a developer who is not the +official maintainer, for the purposes of fixing a bug in the package. +Source NMUs always involves changes to the source (even if it is just +a change to <file>debian/changelog</file>). This can be either a +change to the upstream source, or a change to the Debian bits of the +source. Note, however, that source NMUs may also include +architecture-dependent packages, as well as an updated Debian diff. + <p> +A binary-only NMU is a recompilation and upload of a binary package +for a given architecture. As such, it is usually part of a porting +effort. A binary-only NMU is a non-maintainer uploaded binary version +of a package, with no source changes required. There are many cases +where porters must fix problems in the source in order to get them to +compile for their target architecture; that would be considered a +source NMU rather than a binary-only NMU. As you can see, we don't +distinguish in terminology between porter NMUs and non-porter NMUs. + <p> +Both classes of NMUs, source and binary-only, can be lumped by the +term ``NMU''. However, this often leads to confusion, since most +people think ``source NMU'' when they think ``NMU''. So it's best to +be careful. In this chapter, if we use the unqualified term ``NMU'', +we refer to any type of non-maintainer upload NMUs, whether source and +binary, or binary-only. + + + <sect1 id="nmu-who">Who can do an NMU + <p> +Only official, registered Debian maintainers can do binary or source +NMUs. An official maintainer is someone who has their key in the +Debian key ring. Non-developers, however, are encouraged to download +the source package and start hacking on it to fix problems; however, +rather than doing an NMU, they should just submit worthwhile patches +to the Bug Tracking System. Maintainers almost always appreciate +quality patches and bug reports. + + + <sect1 id="nmu-when">When to do a source NMU + <p> +Guidelines for when to do a source NMU depend on the target +distribution, i.e., stable, unstable, or experimental. Porters have +slightly different rules than non-porters, due to their unique +circumstances (see <ref id="source-nmu-when-porter">). + <p> +When a security bug is detected, the security team may do an NMU. +Please refer to <ref id="bug-security"> for more information. + <p> +During the release cycle (see <ref id="sec-dists">), NMUs which fix +serious or higher severity bugs are encouraged and accepted. Even +during this window, however, you should endeavor to reach the current +maintainer of the package; they might be just about to upload a fix +for the problem. As with any source NMU, the guidelines found in <ref +id="nmu-guidelines"> need to be followed. Special exceptions are made +for <ref id="qa-bsp">. + <p> +Uploading bug fixes to unstable by non-maintainers should only be done +by following this protocol: + <p> +<list> + <item> +Make sure that the package's bugs that the NMU is meant to address are all +filed in the Debian Bug Tracking System (BTS). +If they are not, submit them immediately. + <item> +Wait a few days the response from the maintainer. If you don't get +any response, you may want to help him by sending the patch that fixes +the bug. Don't forget to tag the bug with the "patch" keyword. + <item> +Wait a few more days. If you still haven't got an answer from the +maintainer, send him a mail announcing your intent to NMU the package. +Prepare an NMU as described in <ref id="nmu-guidelines">, test it +carefully on your machine (cf. <ref id="sanitycheck">). +Double check that your patch doesn't have any unexpected side effects. +Make sure your patch is as small and as non-disruptive as it can be. + <item> +Upload your package to incoming in <file>DELAYED/7-day</file> (cf. +<ref id="delayed-incoming">), send the final patch to the maintainer via +the BTS, and explain to them that they have 7 days to react if they want +to cancel the NMU. + <item> +Follow what happens, you're responsible for any bug that you introduced +with your NMU. You should probably use <ref id="pkg-tracking-system"> (PTS) +to stay informed of the state of the package after your NMU. +</list> + <p> +At times, the release manager or an organized group of developers can +announce a certain period of time in which the NMU rules are relaxed. +This usually involves shortening the period during which one is to wait +before uploading the fixes, and shortening the DELAYED period. It is +important to notice that even in these so-called "bug squashing party" +times, the NMU'er has to file bugs and contact the developer first, +and act later. + + <sect1 id="nmu-guidelines">How to do a source NMU + <p> +The following applies to porters insofar as they are playing the dual +role of being both package bug-fixers and package porters. If a +porter has to change the Debian source archive, automatically their +upload is a source NMU and is subject to its rules. If a porter is +simply uploading a recompiled binary package, the rules are different; +see <ref id="porter-guidelines">. + <p> +First and foremost, it is critical that NMU patches to source should +be as non-disruptive as possible. Do not do housekeeping tasks, do +not change the name of modules or files, do not move directories; in +general, do not fix things which are not broken. Keep the patch as +small as possible. If things bother you aesthetically, talk to the +Debian maintainer, talk to the upstream maintainer, or submit a bug. +However, aesthetic changes must <em>not</em> be made in a non-maintainer +upload. + + + <sect2 id="nmu-version">Source NMU version numbering + <p> +Whenever you have made a change to a package, no matter how trivial, +the version number needs to change. This enables our packing system +to function. + <p> +If you are doing a non-maintainer upload (NMU), you should add a new +minor version number to the <var>debian-revision</var> part of the +version number (the portion after the last hyphen). This extra minor +number will start at `1'. For example, consider the package `foo', +which is at version 1.1-3. In the archive, the source package control +file would be <file>foo_1.1-3.dsc</file>. The upstream version is +`1.1' and the Debian revision is `3'. The next NMU would add a new +minor number `.1' to the Debian revision; the new source control file +would be <file>foo_1.1-3.1.dsc</file>. + <p> +The Debian revision minor number is needed to avoid stealing one of +the package maintainer's version numbers, which might disrupt their +work. It also has the benefit of making it visually clear that a +package in the archive was not made by the official maintainer. + <p> +If there is no <var>debian-revision</var> component in the version +number then one should be created, starting at `0.1'. If it is +absolutely necessary for someone other than the usual maintainer to +make a release based on a new upstream version then the person making +the release should start with the <var>debian-revision</var> value +`0.1'. The usual maintainer of a package should start their +<var>debian-revision</var> numbering at `1'. + + + <sect2 id="nmu-changelog"> + <heading>Source NMUs must have a new changelog entry</heading> + <p> +A non-maintainer doing a source NMU must create a changelog entry, +describing which bugs are fixed by the NMU, and generally why the NMU +was required and what it fixed. The changelog entry will have the +non-maintainer's email address in the log entry and the NMU version +number in it. + <p> +By convention, source NMU changelog entries start with the line +<example> + * Non-maintainer upload +</example> + + + <sect2 id="nmu-patch">Source NMUs and the Bug Tracking System + <p> +Maintainers other than the official package maintainer should make as +few changes to the package as possible, and they should always send a +patch as a unified context diff (<tt>diff -u</tt>) detailing their +changes to the Bug Tracking System. + <p> +What if you are simply recompiling the package? If you just need to +recompile it for a single architecture, then you may do a binary-only +NMU as described in <ref id="binary-only-nmu"> which doesn't require any +patch to be sent. If you want the package to be recompiled for all +architectures, then you do a source NMU as usual and you will have to +send a patch. + <p> +If the source NMU (non-maintainer upload) fixes some existing bugs, +these bugs should be tagged <em>fixed</em> in the Bug Tracking +System rather than closed. By convention, only the official package +maintainer or the original bug submitter are allowed to close bugs. +Fortunately, Debian's archive system recognizes NMUs and thus marks +the bugs fixed in the NMU appropriately if the person doing the NMU +has listed all bugs in the changelog with the <tt>Closes: +bug#<var>nnnnn</var></tt> syntax (see <ref id="upload-bugfix"> for +more information describing how to close bugs via the changelog). +Tagging the bugs <em>fixed</em> ensures that everyone knows that the +bug was fixed in an NMU; however the bug is left open until the +changes in the NMU are incorporated officially into the package by +the official package maintainer. + <p> +Also, after doing an NMU, you have to open a new bug and include a +patch showing all the changes you have made. Alternatively you can send +that information to the existing bugs that are fixed by your NMU. +The normal maintainer will either apply the patch or employ an alternate +method of fixing the problem. Sometimes bugs are fixed independently +upstream, which is another good reason to back out an NMU's patch. +If the maintainer decides not to apply the NMU's patch but to release a +new version, the maintainer needs to ensure that the new upstream version +really fixes each problem that was fixed in the non-maintainer release. + <p> +In addition, the normal maintainer should <em>always</em> retain the +entry in the changelog file documenting the non-maintainer upload. + + + <sect2 id="nmu-build">Building source NMUs + <p> +Source NMU packages are built normally. Pick a distribution using the +same rules as found in <ref id="distribution">, follow the other +prescriptions in <ref id="upload">. + <p> +Make sure you do <em>not</em> change the value of the maintainer in +the <file>debian/control</file> file. Your name as given in the NMU entry of +the <file>debian/changelog</file> file will be used for signing the +changes file. + + <sect1 id="ack-nmu">Acknowledging an NMU + <p> +If one of your packages has been NMU'ed, you have to incorporate the +changes in your copy of the sources. This is easy, you just have +to apply the patch that has been sent to you. Once this is done, you +have to close the bugs that have been tagged fixed by the NMU. You +can either close them manually by sending the required mails to the +BTS or by adding the required <tt>closes: #nnnn</tt> in the changelog +entry of your next upload. + <p> +In any case, you should not be upset by the NMU. An NMU is not a +personal attack against the maintainer. It is a proof that +someone cares enough about the package and that they were willing to help +you in your work, so you should be thankful. You may also want to +ask them if they would be interested to help you on a more frequent +basis as co-maintainer or backup maintainer +(see <ref id="collaborative-maint">). + + + <sect id="collaborative-maint"> + <heading>Collaborative maintenance</heading> + <p> +"Collaborative maintenance" is a term describing the sharing of Debian +package maintenance duties by several people. This collaboration is +almost always a good idea, since it generally results in higher quality and +faster bug fix turnaround time. It is strongly recommended that +packages in which a priority of <tt>Standard</tt> or which are part of +the base set have co-maintainers.</p> + <p> +Generally there is a primary maintainer and one or more +co-maintainers. The primary maintainer is the whose name is listed in +the <tt>Maintainer</tt> field of the <file>debian/control</file> file. +Co-maintainers are all the other maintainers.</p> + <p> +In its most basic form, the process of adding a new co-maintainer is +quite easy:<list> + <item> + <p> +Setup the co-maintainer with access to the sources you build the +package from. Generally this implies you are using a network-capable +version control system, such as <prgn>CVS</prgn> or +<prgn>Subversion</prgn>.</p> + </item> + <item> + <p> +Add the co-maintainer's correct maintainer name and address to the +<tt>Uploaders</tt> field in the global part of the +<file>debian/control</file> file. +<example> +Uploaders: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org> +</example> +</p> + </item> + <item> + <p> +Using the PTS (<ref id="pkg-tracking-system">), the co-maintainers +should subscribe themselves to the appropriate source package.</p> + </item> + </list></p> + </sect> + + + + <chapt id="best-pkging-practices"> + <heading>Best Packaging Practices</heading> + <p> +Debian's quality is largely due to the <url id="&url-debian-policy;" +name="Debian Policy">, which defines explicit baseline requirements +which all Debian packages must fulfill. Yet there is also a shared +history of experience which goes beyond the Debian Policy, an +accumulation of years of experience in packaging. Many very +talented people have created great tools, tools which help you, the +Debian maintainer, create and maintain excellent packages. + <p> +This chapter provides some best practices for Debian developers. All +recommendations are merely that, and are not requirements or policy. +These are just some subjective hints, advice and pointers collected +from Debian developers. Feel free to pick and choose whatever works +best for you. + + <sect id="bpp-debian-rules"> + <heading>Best practices for <file>debian/rules</file></heading> + <p> +The following recommendations apply to the <file>debian/rules</file> +file. Since <file>debian/rules</file> controls the build process and +selects the files which go into the package (directly or indirectly), +it's usually the file maintainers spend the most time on. + + <sect1 id="helper-scripts">Helper scripts + <p> +The rationale for using helper scripts in <file>debian/rules</file> is +that lets maintainers use and share common logic among many packages. +Take for instance the question of installing menu entries: you need to +put the file into <file>/usr/lib/menu</file>, and add commands to the +maintainer scripts to register and unregister the menu entries. Since +this is a very common thing for packages to do, why should each +maintainer rewrite all this on their own, sometimes with bugs? Also, +supposing the menu directory changed, every package would have to be +changed. + <p> +Helper scripts take care of these issues. Assuming you comply with +the conventions expected by the helper script, the helper takes care +of all the details. Changes in policy can be made in the helper +script, then packages just need to be rebuilt with the new version of +the helper and no other changes. + <p> +<ref id="tools"> contains a couple of different helpers. The most +common and best (in our opinion) helper system is +<package>debhelper</package>. Previous helper systems, such as +<package>debmake</package>, were "monolithic": you couldn't pick and +choose which part of the helper you found useful, but had to use the +helper to do everything. <package>debhelper</package>, however, is a +number of separate little <prgn>dh_*</prgn> programs. For instance, +<prgn>dh_installman</prgn> installs and compresses man pages, +<prgn>dh_installmenu</prgn> installs menu files, and so on. Thus, it +offers enough flexibility to be able to use the little helper scripts, +where useful, in conjunction with hand-crafted commands in +<file>debian/rules</file>. + <p> +You can get started with <package>debhelper</package> by reading +<manref name="debhelper" section="1">, and looking at the examples +that come with the package. <prgn>dh_make</prgn>, from the +<package>dh-make</package> package (see <ref id="dh-make">), can be +used to convert a "vanilla" source package to a +<package>debhelper</package>ized package. This shortcut, though, +should not convince you that you do not need to bother understanding +the individual <prgn>dh_*</prgn> helpers. If you are going to use a +helper, you do need to take the time to learn to use that helper, to +learn its expectations and behavior. + <p> +Some people feel that vanilla <file>debian/rules</file> files are +better, since you don't have to learn the intricacies of any helper +system. This decision is completely up to you. Use what works for +you. Many examples of vanilla <file>debian/rules</file> files are +available at <url id="&url-rules-files;">. + + + <sect1 id="multiple-patches"> + <heading>Separating your patches into multiple files</heading> + <p> +Big, complex packages may have many bugs that you need to deal with. +If you correct a number of bug directly in the source, if you're not +careful, it can get hard to differentiate the various patches that you +applied. It can get quite messy when you have to update the package +to a new upstream version which integrates some of the fixes (but not +all). You can't take the total set of diffs (e.g., from +<file>.diff.gz</file>) and work out which patch sets to back out as a +unit as bugs are fixed upstream. + <p> +Unfortunately, the packaging system as such currently doesn't provide for +separating the patches into several files. Nevertheless, there are ways to +separate patches: the patch files are shipped within the Debian patch file +(<file>.diff.gz</file>), usually within the <file>debian/</file> directory. +The only difference is that they aren't applied immediately by dpkg-source, +but by the <tt>build</tt> rule of <file>debian/rules</file>. Conversely, +they are reverted in the <tt>clean</tt> rule. + <p> +<prgn>dbs</prgn> is one of the more popular approaches to this. It does all +of the above, and provides a facility for creating new and updating old +patches. See the package <package>dbs</package> for more information and +<package>hello-dbs</package> for an example. + <p> +<prgn>dpatch</prgn> also provides these facilities, but it's intented to be +even easier to use. See the package <package>dpatch</package> for +documentation and examples (in <file>/usr/share/doc/dpatch</file>). + + + <sect1 id="multiple-binary">Multiple binary packages + <p> +A single source package will often build several binary packages, +either to provide several flavors of the same software (e.g., +the <package>vim</package> source package) or to make several small +packages instead of a big one (e.g., if the user can install only the +subset she needs, and thus save some disk space). + <p> +The second case can be easily managed in <file>debian/rules</file>. +You just need to move the appropriate files from the build directory +into the package's temporary trees. You can do this using +<prgn>install</prgn> or <prgn>dh_install</prgn> +from <package>debhelper</package>. Be sure to check the different +permutations of the various packages, ensuring that you have the +inter-package dependencies set right in <file>debian/control</file>. + <p> +The first case is a bit more difficult since it involves multiple +recompiles of the same software but with different configuration +options. The <package>vim</package> source package is an example of how to manage +this using an hand-crafted <file>debian/rules</file> file. + +<!-- &FIXME; Find a good debhelper example with multiple configure/make + cycles --> + </sect1> + </sect> + + + <sect id="bpp-debian-control"> + <heading>Best practices for <file>debian/control</file></heading> + <p> +The following practices are relevant to the +<file>debian/control</file> file. They supplement the <url +id="&url-debian-policy;ch-miscellaneous.html#s-descriptions" +name="Policy on package descriptions">. + <p> +The description of the package, as defined by the corresponding field +in the <file>control</file> file, contains both the package synopsis +and the long description for the package. <ref id="bpp-desc-basics"> +describes common guidelines for both parts of the package description. +Following that, <ref id="bpp-pkg-synopsis"> provides guidelines +specific to the synopsis, and <ref id="bpp-pkg-desc"> contains +guidelines specific to the description. + + <sect1 id="bpp-desc-basics"> + <heading>General guidelines for package descriptions</heading> + <p> +The package description should be written for the average likely user, +the average person who will use and benefit from the package. For +instance, development packages are for developers, and can be +technical in their language. More general-purpose applications, such +as editors, should be written for a less technical user. + <p> +Our review of package descriptions lead us to conclude that most +package descriptions are technical, that is, are not written to make +sense for non-technical users. Unless your package really is only for +technical users, this is a problem. + <p> +How do you write for non-technical users? Avoid jargon. Avoid +referring to other applications or frameworks that the user might not +be familiar with — "GNOME" or "KDE" is fine, since users are +probably familiar with these terms, but "GTK+" is +probably not. Try not to assume any knowledge at all. If you must +use technical terms, introduce them. + <p> +Be objective. Package descriptions are not the place for advocating +your package, no matter how much you love it. Remember that the +reader may not care about the same things you care about. + <p> +References to the names of any other software packages, protocol names, +standards, or specifications should use their canonical forms, if one +exists. For example, use "X Window System", "X11", or "X"; not "X +Windows", "X-Windows", or "X Window". Use "GTK+", not "GTK" or "gtk". +Use "GNOME", not "Gnome". Use "PostScript", not "Postscript" or +"postscript". + <p> +If you are having problems writing your description, you may wish to +send it along to &email-debian-l10n-english; and request feedback. + </sect1> + + + <sect1 id="bpp-pkg-synopsis"> + <heading>The package synopsis, or short description</heading> + <p> +The synopsis line (the short description) should be concise. It +must not repeat the package's name (this is policy). + <p> +It's a good idea to think of the synopsis as an appositive clause, not +a full sentence. An appositive clause is defined in WordNet as a +grammatical relation between a word and a noun phrase that follows, +e.g., "Rudolph the red-nosed reindeer". The appositive clause here is +"red-nosed reindeer". Since the synopsis is a clause, rather than a +full sentence, we recommend that it neither start with a capital nor +end with a full stop (period). It should also not begin with an +article, either definite ("the") or indefinite ("a" or "an"). + <p> +It might help to imagine that the synopsis is combined with the +package name in the following way: + +<example><var>package-name</var> is a <var>synopsis</var>.</example> + +Alternatively, it might make sense to think of it as + +<example><var>package-name</var> is <var>synopsis</var>.</example> + +or, if the package name itself is a plural (such as +"developers-tools") + +<example><var>package-name</var> are <var>synopsis</var>.</example> + +This way of forming a sentance from the package name and synopsis +should be considered as a heuristic and not a strict rule. There are +some cases where it doesn't make sense to try to form a sentance. + </sect1> + + <sect1 id="bpp-pkg-desc"> + <heading>The long description</heading> + <p> +The long description is the primary information available to the user +about a package before they install it. It should provide all the +information needed to let the user decide whether to install the +package. Assume that the user has already read the package synopsis. + <p> +The long description should consist of full and complete sentences. + <p> +The first paragraph of the long description should answer the +following questions: what does the package do? what task does it help +the user accomplish? It is important to describe this in a +non-technical way, unless of course the audience for the package is +necessarily technical. + <p> +The following paragraphs should answer the following questions: Why do +I as a user need this package? What other features does the package +have? What outstanding features and deficiencies are there compared +to other packages (e.g., "if you need X, use Y instead")? Is this +package related to other packages in some way that is not handled by +the package manager (e.g., "this is the client to the foo server")? + <p> +Be careful to avoid spelling and grammar mistakes. Ensure that you +spell-check it. <prgn>ispell</prgn> has a special <tt>-g</tt> option +for <file>debian/control</file> files: + +<example>ispell -d american -g debian/control</example> + </sect1> + + + <sect1 id="bpp-upstream-info"> + <heading>Upstream home page</heading> + <p> +We recommend that you add the URL for the package's home page to the +package description in <file>debian/control</file>. This information +should be added at the +end of description, using the following format: + +<example> . + Homepage: http://some-project.some-place.org/</example> + +Note the spaces prepending the line, which serves to break the lines +correctly. To see an example of how this displays, see <url +id="&url-eg-desc-upstream-info;">. + <p> +If there is no home page for the software, this should naturally be +left out. + <p> +Note that we expect this field will eventually be replaced by a proper +<file>debian/control</file> field understood by <prgn>dpkg</prgn> and +<tt>&packages-host;</tt>. If you don't want to bother migrating the +home page from the description to this field, you should probably wait +until that is available.</p> + </sect1> + </sect> + + + <sect id="bpp-debian-changelog"> + <heading>Best practices for <file>debian/changelog</file></heading> + <p> +The following practices supplement the <url name="Policy on changelog +files" id="&url-debian-policy;ch-docs.html#s-changelogs">.</p> + + <sect1 id="bpp-changelog-do"> + <heading>Writing useful changelog entries</heading> + <p> +The changelog entry for a package revision documents changes in that +revision, and only them. Concentrate on describing significant and +user-visible changes that were made since the last version. + <p> +Focus on <em>what</em> was changed — who, how and when are +usually less important. Having said that, remember to politely +attribute people who have provided notable help in making the package +(e.g., those who have sent in patches). + <p> +There's no need to elaborate the trivial and obvious changes. You can +also aggregate several changes in one entry. On the other hand, don't +be overly terse if you have undertaken a major change. Be especially +clear if there are changes that affect the behaviour of the program. +For further explanations, use the <file>README.Debian</file> file. + <p> +Use common English so that the majority of readers can comprehend it. +Avoid abbreviations, "tech-speak" and jargon when explaining changes +that close bugs, especially for bugs filed by users that did not +strike you as particularly technically savvy. Be polite, don't swear. + <p> +It is sometimes desirable to prefix changelog entries with the names +of the files that were changed. However, there's no need to +explicitly list each and every last one of the changed files, +especially if the change was small or repetitive. You may use +wildcards. + <p> +When referring to bugs, don't assume anything. Say what the problem +was, how it was fixed, and append the "closes: #nnnnn" string. See +<ref id="upload-bugfix"> for more information. + + + <sect1 id="bpp-changelog-misconceptions"> + <heading>Common misconceptions about changelog entries</heading> + <p> +The changelog entries should <strong>not</strong> document generic +packaging issues ("Hey, if you're looking for foo.conf, it's in +/etc/blah/."), since administrators and users are supposed to be at +least remotely acquainted with how such things are generally arranged +on Debian systems. Do, however, mention if you change the location of +a configuration file. + <p> +The only bugs closed with a changelog entry should be those that are +actually fixed in the same package revision. Closing unrelated bugs +in the changelog is bad practice. See <ref id="upload-bugfix">. + <p> +The changelog entries should <strong>not</strong> be used for random +discussion with bug reporters ("I don't see segfaults when starting +foo with option bar; send in more info"), general statements on life, +the universe and everything ("sorry this upload took me so long, but I +caught the flu"), or pleas for help ("the bug list on this package is +huge, please lend me a hand"). Such things usually won't be noticed +by their target audience, but may annoy people who wish to read +information about actual changes in the package. See <ref +id="bug-answering"> for more information on how to use the bug +tracking system. + <p> +It is an old tradition to acknowledge bugs fixed in non-maintainer +uploads in the first changelog entry of the proper maintainer upload, +for instance, in a changelog entry like this: +<example> + * Maintainer upload, closes: #42345, #44484, #42444. +</example> +This will close the NMU bugs tagged "fixed" when the package makes +it into the archive. The bug for the fact that an NMU was done can be +closed the same way. Of course, it's also perfectly acceptable to +close NMU-fixed bugs by other means; see <ref id="bug-answering">. + </sect1> + + <sect1 id="bpp-changelog-errors"> + <heading>Common errors in changelog entries</heading> + <p> +The following examples demonstrate some common errors or example of +bad style in changelog entries. + + <p> +<example> + * Fixed all outstanding bugs. +</example> +This doesn't tell readers anything too useful, obviously. + + <p> +<example> + * Applied patch from Jane Random. +</example> +What was the patch about? + + <p> +<example> + * Late night install target overhaul. +</example> +Overhaul which accomplished what? Is the mention of late night +supposed to remind us that we shouldn't trust that code? + + <p> +<example> + * Fix vsync FU w/ ancient CRTs. +</example> +Too many acronyms, and it's not overly clear what the, uh, fsckup (oops, +a curse word!) was actually about, or how it was fixed. + + <p> +<example> + * This is not a bug, closes: #nnnnnn. +</example> +First of all, there's absolutely no need to upload the package to +convey this information; instead, use the bug tracking system. +Secondly, there's no explanation as to why the report is not a bug. + + <p> +<example> + * Has been fixed for ages, but I forgot to close; closes: #54321. +</example> +If for some reason you didn't mention the bug number in a previous changelog +entry, there's no problem, just close the bug normally in the BTS. There's +no need to touch the changelog file, presuming the description of the fix is +already in (this applies to the fixes by the upstream authors/maintainers as +well, you don't have to track bugs that they fixed ages ago in your +changelog). + + <p> +<example> + * Closes: #12345, #12346, #15432 +</example> +Where's the description? If you can't think of a descriptive message, +start by inserting the title of each different bug. + </sect1> + </sect> + +<!-- + <sect1 id="pkg-mgmt-cvs">Managing a package with CVS + <p> + &FIXME; presentation of cvs-buildpackage, updating sources + via CVS (debian/rules refresh). + <url id="http://www.debian.org/devel/cvs_packages"> +--> + + + <sect id="bpp-debian-maint-scripts"> + <heading>Best practices for maintainer scripts</heading> + <p> +Maintainer scripts include the files <file>debian/postinst</file>, +<file>debian/preinst</file>, <file>debian/prerm</file> and +<file>debian/postrm</file>. These scripts take care of any package +installation or deinstallation setup which isn't handled merely by the +creation or removal of files and directories. The following +instructions supplement the <url id="&url-debian-policy;" name="Debian +Policy">. + <p> +Maintainer scripts must be idempotent. That means that you need to +make sure nothing bad will happen if the script is called twice where +it would usually be called once. + <p> +Standard input and output may be redirected (e.g. into pipes) for +logging purposes, so don't rely on them being a tty. + <p> +All prompting or interactive configuration should be kept to a +minimum. When it is necessary, you should use the +<package>debconf</package> package for the interface. Remember that +prompting in any case can only be in the <tt>configure</tt> stage of +the <file>postinst</file> script. + <p> +Keep the maintainer scripts as simple as possible. We suggest you use +pure POSIX shell scripts. Remember, if you do need any bash features, +the maintainer script must have a bash sh-bang line. POSIX shell or +Bash are preferred to Perl, since they enable +<package>debhelper</package> to easily add bits to the scripts. + <p> +If you change your maintainer scripts, be sure to test package +removal, double installation, and purging. Be sure that a purged +package is completely gone, that is, it must remove any files created, +directly or indirectly, in any maintainer script. + <p> +If you need to check for the existence of a command, you should use +something like +<example>if [ -x /usr/sbin/install-docs ]; then ...</example> + +If you don't wish to hard-code the path of the command in your +maintainer script, the following POSIX-compliant shell function may +help: + +&example-pathfind; + +You can use this function to search <tt>$PATH</tt> for a command name, +passed as an argument. It returns true (zero) if the command was +found, and false if not. This is really the most portable way, since +<tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not +POSIX. + <p> +While <prgn>which</prgn> is an acceptable alternative, since +it is from the required <package>debianutils</package> package, it's +not on the root partition. That is, it's in <file>/usr/bin</file> rather +than <file>/bin</file>, so one can't use it in scripts which are run +before the <file>/usr</file> partition is mounted. Most scripts won't have +this problem, though. + </sect> + + + <sect id="bpp-config-mgmt"> + <heading>Configuration management with <package>debconf</package></heading> + <p> +<package>Debconf</package> is a configuration management system which +can be used by all the various packaging scripts +(<file>postinst</file> mainly) to request feedback from the user +concerning how to configure the package. Direct user interactions must +now be avoided in favor of <package>debconf</package> +interaction. This will enable non-interactive installations in the +future. + <p> +Debconf is a great tool but it is often poorly used. Many common mistakes +are listed in the <manref name="debconf-devel" section="8"> man page. +It is something that you must read if you decide to use debconf. + </sect> + + + <sect id="bpp-i18n"> + <heading>Internationalization</heading> + + <sect1 id="bpp-i18n-debconf"> + <heading>Handling debconf translations</heading> + <p> +Like porters, translators have a difficult task. They work on many +packages and must collaborate with many different +maintainers. Moreover, most of the time, they are not native English +speakers, so you may need to be particularly patient with them. + <p> +The goal of <package>debconf</package> was to make packages +configuration easier for maintainers and for users. Originally, +translation of debconf templates was handled with +<prgn>debconf-mergetemplate</prgn>. However, that technique is now +deprecated; the best way to accomplish <package>debconf</package> +internationalization is by using the <package>po-debconf</package> +package. This method is easier both for maintainer and translators; +transition scripts are provided. + <p> +Using <package>po-debconf</package>, the translation is stored in +<file>po</file> files (drawing from <prgn>gettext</prgn> translation +techniques). Special template files contain the original messages and +mark which fields are translatable. When you change the value of a +translatable field, by calling <prgn>debconf-updatepo</prgn>, the +translation is marked as needing attention from the translators. Then, +at build time, the <prgn>dh_installdebconf</prgn> program takes care +of all the needed magic to add the template along with the up-to-date +translations into the binary packages. Refer to the <manref +name="po-debconf" section="7"> manual page for details. + </sect1> + + <sect1 id="bpp-i18n-docs"> + <heading>Internationalized documentation</heading> + <p> +Internationalizing documentation is crucial for users, but a lot of +labor. There's no way to eliminate all that work, but you can make things +easier for translators. + <p> +If you maintain documentation of any size, its easier for translators +if they have access to a source control system. That lets translators +see the differences between two versions of the documentation, so, for +instance, they can see what needs to be retranslated. It is +recommended that the translated documentation maintain a note about +what source control revision the translation is based on. An +interesting system is provided by <url id="&url-i18n-doc-check;" +name="doc-check"> in the <package>boot-floppies</package> package, +which shows an overview of the translation status for any given +language, using structured comments for the current revision of the +file to be translated and, for a translated file, the revision of the +original file the translation is based on. You might wish to adapt +and provide that in your CVS area. + <p> +If you maintain XML or SGML documentation, we suggest that you isolate +any language-independent information and define those as entities in a +separate file which is included by all the different +translations. This makes it much easier, for instance, to keep URLs +up-to-date across multiple files. + </sect1> + </sect> + + <sect id="bpp-common-situations"> + <heading>Common packaging situations</heading> + +<!-- + <sect1 id="bpp-kernel">Kernel modules/patches + <p> + &FIXME; Heavy use of kernel-package. provide files in + /etc/modutils/ for module configuration. +--> + + <sect1 id="bpp-autotools"> + <heading>Packages using + <prgn>autoconf</prgn>/<prgn>automake</prgn></heading> + <p> +Keeping <prgn>autoconf</prgn>'s <file>config.sub</file> and +<file>config.guess</file> files up-to-date is critical for porters, +especially on more volatile architectures. Some very good packaging +practices for any package using <prgn>autoconf</prgn> and/or +<prgn>automake</prgn> have been synthesized in +&file-bpp-autotools; from the <package>autotools-dev</package> +package. You're strongly encouraged to read this file and +to follow the given recommendations. + + + <sect1 id="bpp-libraries">Libraries + <p> +Libraries are always difficult to package for various reasons. The policy +imposes many constraints to ease their maintenance and to make sure +upgrades are as simple as possible when a new upstream version comes out. +A breakage in a library can result in dozens of dependent packages +breaking. + <p> +Good practices for library packaging have been grouped in +<url id="&url-libpkg-guide;" name="the library packaging guide">. + + + <sect1 id="bpp-docs">Documentation + <p> +Be sure to follow the <url id="&url-debian-policy;ch-docs.html" + name="Policy on documentation">.</p> + <p> +If your package contains documentation built from XML or SGML, we +recommend you not ship the XML or SGML source in the binary +package(s). If users want the source of the documentation, they +should retrieve the source package.</p> + <p> +Policy specifies that documentation should be shipped in HTML format. +We also recommend shipping documentation in PDF and plain text format if +convenient and quality output is possible. However, it is generally +not appropriate to ship plain text versions of documentation whose source +format is HTML.</p> + <p> +Major shipped manuals should register themselves with +<package>doc-base</package> on installation. See the +<package>doc-base</package> package documentation for more +information.</p> + + + <sect1 id="bpp-other">Specific types of packages + <p> +Several specific types of packages have special sub-policies and +corresponding packaging rules and practices: +<list> + <item> +Perl related packages have a <url name="Perl policy" +id="&url-perl-policy;">, some examples of packages following that +policy are <package>libdbd-pg-perl</package> (binary perl module) or +<package>libmldbm-perl</package> (arch independent perl module). + <item> +Python related packages have their python policy; see +&file-python-policy; in the <package>python</package> package. + <item> +Emacs related packages have the <url id="&url-emacs-policy;" +name="emacs policy">. + <item> +Java related packages have their <url id="&url-java-policy;" +name="java policy">. + <item> +Ocaml related packages have their own policy, found in +&file-ocaml-policy; from the <package>ocaml</package> package. A good +example is the <package>camlzip</package> source package. + <item> +Packages providing XML or SGML DTDs should conform to the +recommendations found in the <package>sgml-base-doc</package> +package. + <item> +Lisp packages should register themselves with +<package>common-lisp-controller</package>, about which see +&file-lisp-controller;. +</list> + </sect1> + +<!-- + <sect1 id="custom-config-files">Custom configuration files + <p> + &FIXME; speak of "ucf", explain solution with a template, + explain conf.d directories + + <sect1 id="config-with-db">Use of an external database + <p> + &FIXME; The software may require a database that you need to setup. + But the database may be local or distant. Thus you can't depend + on a database server but just on the corresponding library. + + sympa may be an example package +--> + + <sect1 id="bpp-archindepdata"> + <heading>Architecture-independent data</heading> + <p> +It is not uncommon to have a large amount of architecture-independent +data packaged with a program. For example, audio files, a collection +of icons, wallpaper patterns, or other graphic files. If the size of +this data is negligible compared to the size of the rest of the +package, it's probably best to keep it all in a single package. + <p> +However, if the size of the data is considerable, consider splitting +it out into a separate, architecture-independent package ("_all.deb"). +By doing this, you avoid needless duplication of the same data into +eleven or more .debs, one per each architecture. While this +adds some extra overhead into the <file>Packages</file> files, it +saves a lot of disk space on Debian mirrors. Separating out +architecture-independent data also reduces processing time of +<prgn>lintian</prgn> or <prgn>linda</prgn> (see <ref id="tools-lint">) +when run over the entire Debian archive. + </sect1> + </sect> + + </chapt> + + + <chapt id="beyond-pkging"> + <heading>Beyond Packaging</heading> + <p> +Debian is about a lot more than just packaging software and +maintaining those packages. This chapter contains information about +ways, often really critical ways, to contribute to Debian beyond +simply creating and maintaining packages. + <p> +As a volunteer organization, Debian relies on the discretion of its +members in choosing what they want to work on and in choosing +the most critical thing to spend their time on. + + <sect id="submit-bug"> + <heading>Bug reporting</heading> + <p> +We encourage you to file bugs as you find them in Debian packages. In +fact, Debian developers are often the first line testers. Finding and +reporting bugs in other developers' packages improves the quality of +Debian. + <p> +Read the <url name="instructions for reporting bugs" +id="&url-bts-report;"> in the Debian <url name="bug tracking system" +id="&url-bts;">. + <p> +Try to submit the bug from a normal user account at which you are +likely to receive mail, so that people can reach you if they need +further information about the bug. Do not submit bugs as root. + <p> +You can use a tool like <manref name="reportbug" section="1"> to +submit bugs. It can automate and generally ease the process. + <p> +Make sure the bug is not already filed against a package. +Each package has a bug list easily reachable at +<tt>http://&bugs-host;/<var>packagename</var></tt> +Utilities like <manref name="querybts" section="1"> can also +provide you with this information (and <prgn>reportbug</prgn> +will usually invoke <prgn>querybts</prgn> before sending, too). + <p> +Try to direct your bugs to the proper location. When for example +your bug is about a package that overwrites files from another package, +check the bug lists for <em>both</em> of those packages in order to +avoid filing duplicate bug reports. + <p> +For extra credit, you can go through other packages, merging bugs +which are reported more than once, or tagging bugs `fixed' +when they have already been fixed. Note that when you are +neither the bug submitter nor the package maintainer, you should +not actually close the bug (unless you secure permission from the +maintainer). + <p> +From time to time you may want to check what has been going on +with the bug reports that you submitted. Take this opportunity to +close those that you can't reproduce anymore. To find +out all the bugs you submitted, you just have to visit +<tt>http://&bugs-host;/from:<var><your-email-addr></var></tt>. + + <sect1 id="submit-many-bugs">Reporting lots of bugs at once + <p> +Reporting a great number of bugs for the same problem on a great +number of different packages — i.e., more than 10 — is a deprecated +practice. Take all possible steps to avoid submitting bulk bugs at +all. For instance, if checking for the problem can be automated, add +a new check to <package>lintian</package> so that an error or warning +is emitted. + <p> +If you report more than 10 bugs on the same topic at once, it is +recommended that you send a message to &email-debian-devel; describing +your intention before submitting the report. This will allow other +developers to verify that the bug is a real problem. In addition, it +will help prevent a situation in which several maintainers start +filing the same bug report simultaneously. + <p> +Note that when sending lots of bugs on the same subject, you should +send the bug report to <email>maintonly@&bugs-host;</email> so +that the bug report is not forwarded to the bug distribution mailing +list. + + + <sect id="qa-effort">Quality Assurance effort + + <sect1 id="qa-daily-work">Daily work + <p> +Even though there is a dedicated group of people for Quality +Assurance, QA duties are not reserved solely for them. You can +participate in this effort by keeping your packages as bug-free as +possible, and as lintian-clean (see <ref id="lintian">) as +possible. If you do not find that possible, then you should consider +orphaning some of your packages (see <ref +id="orphaning">). Alternatively, you may ask the help of other people +in order to catch up the backlog of bugs that you have (you can ask +for help on &email-debian-qa; or &email-debian-devel;). At the same +time, you can look for co-maintainers (see <ref id="collaborative-maint">). + + <sect1 id="qa-bsp">Bug squashing parties + <p> +From time to time the QA group organizes bug squashing parties to get rid of +as many problems as possible. They are announced on &email-debian-devel-announce; +and the announce explains what area will be focused on during the party: +usually they focus on release critical bugs but it may happen that they +decide to help finish a major upgrade going on (like a new perl version +which requires recompilation of all the binary modules). + <p> +The rules for non-maintainer uploads differ during the parties because +the announce of the party is considered like a prior notice for NMU. If +you have packages that may be affected by the party (because they have +release critical bugs for example), you should send an update to each of +the corresponding bug to explain their current status and what you expect +from the party. If you don't want an NMU, or if you're only interested in a +patch, or if you will deal yourself with the bug, please explain that in +the BTS. + <p> +People participating in the party have special rules for NMU, they can +NMU without prior notice if they upload their NMU to +DELAYED/3-day at least. All other NMU rules applies as usually, they +should send the patch of the NMU in the BTS (in one of the open bugs +fixed by the NMU or in a new bug tagged fixed). They should +also respect the maintainer's wishes if he expressed some. + <p> +If someone doesn't feel confident with an NMU, he should just send a patch +to the BTS. It's far better than a broken NMU. + + + <sect id="contacting-maintainers">Contacting other maintainers + <p> +During your lifetime within Debian, you will have to contact other +maintainers for various reasons. You may want to discuss a new +way of cooperating between a set of related packages, or you may +simply remind someone that a new upstream version is available +and that you need it. + <p> +Looking up the email address of the maintainer for the package can be +distracting. Fortunately, there is a simple email alias, +<tt><package>@&packages-host;</tt>, which provides a way to +email the maintainer, whatever their individual email address (or +addresses) may be. Replace <tt><package></tt> with the name of +a source or a binary package. + <p> +You may also be interested in contacting the persons who are +subscribed to a given source package via <ref id="pkg-tracking-system">. +You can do so by using the <tt><package-name>@&pts-host;</tt> +email address. + + + <sect id="mia-qa">Dealing with inactive and/or unreachable maintainers + <p> +If you notice that a package is lacking maintenance, you should +make sure that the maintainer is active and will continue to work on +their packages. It is possible that they are not active any more, but +haven't registered out of the system, so to speak. On the other hand, +it is also possible that they just need a reminder. + <p> +The first step is to politely contact the maintainer, and wait for a +response, for a reasonable time. It is quite hard to define "reasonable +time", but it is important to take into account that real life is sometimes +very hectic. One way to handle this would be send a reminder after two +weeks. + <p> +If the maintainer doesn't reply within four weeks (a month), one can +assume that a response will probably not happen. If that happens, you +should investigate further, and try to gather as much useful information +about the maintainer in question as possible. This includes: + <p> + <list> + <item>The "echelon" information available through the + <url id="&url-debian-db;" name="developers' LDAP database">, + which indicates when's the last time a developer has posted to + a Debian mailing list. (This includes uploads via + debian-*-changes lists.) Also, remember to check whether the + maintainer is marked as "on vacation" in the database. + + <item>The number of packages this maintainer is responsible for, + and the condition of those packages. In particular, are there + any RC bugs that have been open for ages? Furthermore, how + many bugs are there in general? Another important piece of + information is whether the packages have been NMUed, and if + so, by whom? + + <item>Is there any activity of the maintainer outside of Debian? + For example, they might have posted something recently to + non-Debian mailing lists or news groups. + </list> + <p> +One big problem are packages which were sponsored -- the maintainer is not +an official Debian developer. The echelon information is not available for +sponsored people, for example, so you need to find and contact the Debian +developer who has actually uploaded the package. Given that they signed the +package, they're responsible for the upload anyhow, and should know what +happened to the person they sponsored. + <p> +It is also allowed to post a query to &email-debian-devel;, asking if anyone +is aware of the whereabouts of the missing maintainer. + <p> +Once you have gathered all of this, you can contact &email-debian-qa;. +People on this alias will use the information you provided in order to +decide how to proceed. For example, they might orphan one or all of the +packages of the maintainer. If a packages has been NMUed, they might prefer +to contact the NMUer before orphaning the package -- perhaps the person who +has done the NMU is interested in the package. + <p> +One last word: please remember to be polite. We are all volunteers and +cannot dedicate all of our time to Debian. Also, you are not aware of the +circumstances of the person who is involved. Perhaps they might be +seriously ill or might even had died -- you do not know who may be on the +receiving side -- imagine how a relative will feel if they read the e-mail +of the deceased and find a very impolite, angry and accusing message!) + <p> +On the other hand, although we are volunteers, we do have a responsibility. +So you can stress the importance of the greater good -- if a maintainer does +not have the time or interest anymore, they should "let go" and give the +package to someone with more time. + + + <sect id="newmaint"> + <heading>Interacting with prospective Debian developers</heading> + <p> +Debian's success depends on its ability to attract and retain new and +talented volunteers. If you are an experienced developer, we +recommend that you get involved with the process of bringing in new +developers. This section describes how to help new prospective +developers. + + + <sect1 id="sponsoring">Sponsoring packages + <p> +Sponsoring a package means uploading a package for a maintainer who is not +able to do it on their own, a new maintainer applicant. Sponsoring a package +also means accepting responsibility for it. + <p> +If you wish to volunteer as a sponsor, you can sign up at <url +id="&url-sponsors;">. + <p> +New maintainers usually have certain difficulties creating Debian packages +— this is quite understandable. That is why the sponsor is there, to check +the package and verify that it is good enough for inclusion in Debian. +(Note that if the sponsored package is new, the ftpmasters will also have to +inspect it before letting it in.) + <p> +Sponsoring merely by signing the upload or just recompiling is +<strong>definitely not recommended</strong>. You need to build the source +package just like you would build a package of your own. Remember that it +doesn't matter that you left the prospective developer's name both in the +changelog and the control file, the upload can still be traced to you. + <p> +If you are an application manager for a prospective developer, you can also +be their sponsor. That way you can also verify how the applicant is +handling the 'Tasks and Skills' part of their application. + + <sect1>Managing sponsored packages + <p> +By uploading a sponsored package to Debian, you are certifying that +the package meets minimum Debian standards. That implies that you +must build and test the package on your own system before uploading. + <p> +You can not simply upload a binary <file>.deb</file> from the sponsoree. In +theory, you should only ask for the diff file and the location of the +original source tarball, and then you should download the source and apply +the diff yourself. In practice, you may want to use the source package +built by your sponsoree. In that case, you have to check that they haven't +altered the upstream files in the <file>.orig.tar.gz</file> file that +they're providing. + <p> +Do not be afraid to write the sponsoree back and point out changes +that need to be made. It often takes several rounds of back-and-forth +email before the package is in acceptable shape. Being a sponsor +means being a mentor. + <p> +Once the package meets Debian standards, build the package with +<example>dpkg-buildpackage -us -uc</example> and sign it +with <example>debsign -m"<var>FULLNAME</var> <var>email-addr</var>" <var>changes-file</var></example> +before uploading it to the incoming directory. + <p> +The Maintainer field of the <file>control</file> file and the +<file>changelog</file> should list the person who did the packaging, i.e., the +sponsoree. The sponsoree will therefore get all the BTS mail about the +package. + <p> +If you prefer to leave a more evident trace of your sponsorship job, you +can add a line stating it in the most recent changelog entry. + <p> +You are encouraged to keep tabs on the package you sponsor using +<ref id="pkg-tracking-system">. + + <sect1>Advocating new developers + <p> +See the page about <url id="&url-newmaint-advocate;" +name="advocating a prospective developer"> at the Debian web site. + + <sect1>Handling new maintainer applications + <p> +Please see <url id="&url-newmaint-amchecklist;" name="Checklist for +Application Managers"> at the Debian web site. + + + + <appendix id="tools">Overview of Debian Maintainer Tools + <p> +This section contains a rough overview of the tools available to +maintainers. The following is by no means complete or definitive, but +just a guide to some of the more popular tools. + <p> +Debian maintainer tools are meant to help convenience developers and +free their time for critical tasks. As Larry Wall says, there's more +than one way to do it. + <p> +Some people prefer to use high-level package maintenance tools and +some do not. Debian is officially agnostic on this issue; any tool +which gets the job done is fine. Therefore, this section is not meant +to stipulate to anyone which tools they should use or how they should +go about with their duties of maintainership. Nor is it meant to +endorse any particular tool to the exclusion of a competing tool. + <p> +Most of the descriptions of these packages come from the actual +package descriptions themselves. Further information can be found in +the package documentation itself. You can also see more info with the +command <tt>apt-cache show <package-name></tt>.</p> + + <sect id="tools-core"> + <heading>Core tools</heading> + <p> +The following tools are pretty much required for any maintainer.</p> + + <sect1 id="dpkg-dev"> + <heading><package>dpkg-dev</package> + <p> +<package>dpkg-dev</package> contains the tools (including +<prgn>dpkg-source</prgn>) required to unpack, build and upload Debian +source packages. These utilities contain the fundamental, low-level +functionality required to create and manipulated packages; as such, +they are required for any Debian maintainer. + + <sect1 id="debconf"> + <heading><package>debconf</package></heading> + <p> +<package>debconf</package> provides a consistent interface to +configuring packages interactively. It is user interface +independent, allowing end-users to configure packages with a +text-only interface, an HTML interface, or a dialog interface. New +interfaces can be added modularly. + <p> +You can find documentation for this package in the +<package>debconf-doc</package> package. + <p> +Many feel that this system should be used for all packages requiring +interactive configuration; see <ref id="bpp-config-mgmt">. +<package>debconf</package> is not currently required by Debian Policy, +but that may change in the future. + </sect1> + + <sect1 id="fakeroot"> + <heading><package>fakeroot</package> + <p> +<package>fakeroot</package> simulates root privileges. This enables +you to build packages without being root (packages usually want to +install files with root ownership). If you have +<package>fakeroot</package> installed, you can build packages as a +user: <tt>dpkg-buildpackage -rfakeroot</tt>. + </sect1> + </sect> + + <sect id="tools-lint"> + <heading>Package lint tools</heading> + <p> +According to the Free On-line Dictionary of Computing (FOLDOC), `lint' +is "a Unix C language processor which carries out more thorough checks +on the code than is usual with C compilers." Package lint tools help +package maintainers by automatically finding common problems and +policy violations with their packages.</p> + + <sect1 id="lintian"> + <heading><package>lintian</package></heading> + <p> +<package>lintian</package> dissects Debian packages and emits +information on bugs +and policy violations. It contains automated checks for many aspects +of Debian policy as well as some checks for common errors. + <p> +You should periodically get the newest <package>lintian</package> from +`unstable' and check over all your packages. Notice that the <tt>-i</tt> +option provides detailed explanations of what each error or warning means, +what is its basis in Policy, and commonly how you can fix the problem. + <p> +Refer to <ref id="sanitycheck"> for more information on how and when +to use Lintian. + <p> +You can also see a summary of all problems reported by Lintian on your +packages at <url id="&url-lintian;">. Those reports contain the latest +<prgn>lintian</prgn> output on the whole development distribution +("unstable"). + </sect1> + + <sect1 id="linda"> + <heading><package>linda</package></heading> + <p> +<package>linda</package> is another package linter. It is similar to +<package>lintian</package> but has a different set of checks. Its +written in Python rather than Perl.</p> + </sect1> + + <sect1 id="debdiff"> + <heading><package>debdiff</package></heading> + <p> +<prgn>debdiff</prgn> (from the <package>devscripts</package> package, <ref id="devscripts">) +compares file lists and control files of two packages. It is a simple +regression test, as it will help you notice if the number of binary +packages has changed since the last upload, or if something's changed +in the control file. Of course, some of the changes it reports will be +all right, but it can help you prevent various accidents. + <p> +You can run it over a pair of binary packages: +<example> +debdiff package_1-1_arch.deb package_2-1_arch.deb +</example> + <p> +Or even a pair of changes files: +<example> +debdiff package_1-1_arch.changes package_2-1_arch.changes +</example> + <p> +For more information please see <manref name="debdiff" section="1">. + </sect1> + + </sect> + + + <sect id="tools-helpers"> + <heading>Helpers for <file>debian/rules</file></heading> + <p> +Package building tools make the process of writing +<file>debian/rules</file> files easier. See <ref id="helper-scripts"> +for more information on why these might or might not be desired. + + <sect1 id="debhelper"> + <heading><package>debhelper</package></heading> + <p> +<package>debhelper</package> is a collection of programs that can be +used in <file>debian/rules</file> to automate common tasks related to +building binary Debian packages. Programs are included to install +various files into your package, compress files, fix file permissions, +integrate your package with the Debian menu system. + <p> +Unlike some approaches, <package>debhelper</package> is broken into +several small, granular commands which act in a consistent manner. As +such, it allows a greater granularity of control than some of the +other "debian/rules tools". + <p> +There are a number of little <package>debhelper</package> add-on +packages, too transient to document. You can see the list of most of +them by doing <tt>apt-cache search ^dh-</tt>. + </sect1> + + <sect1 id="debmake"> + <heading><package>debmake</package> + <p> +<package>debmake</package>, a pre-cursor to +<package>debhelper</package>, is a less granular +<file>debian/rules</file> assistant. It includes two main programs: +<prgn>deb-make</prgn>, which can be used to help a maintainer convert +a regular (non-Debian) source archive into a Debian source package; +and <prgn>debstd</prgn>, which incorporates in one big shot the same +sort of automated functions that one finds in +<package>debhelper</package>. + <p> +The consensus is that <package>debmake</package> is now deprecated in +favor of <package>debhelper</package>. However, it's not a bug to use +<package>debmake</package>. + </sect1> + + <sect1 id="dh-make"> + <heading><package>dh-make</package> + <p> +The <package/dh-make/ package contains <prgn/dh_make/, a program that +creates a skeleton of files necessary to build a Debian package out of +a source tree. As the name suggests, <prgn/dh_make/ is a rewrite of +<package/debmake/ and its template files use dh_* programs from +<package/debhelper/. + <p> +While the rules files generated by <prgn/dh_make/ are in general a +sufficient basis for a working package, they are still just the groundwork: +the burden still lies on the maintainer to finely tune the generated files +and make the package entirely functional and Policy-compliant. + </sect1> + + <sect1 id="yada"> + <heading><package>yada</package> + <p> +<package>yada</package> is another packaging helper tool. It uses a +<file>debian/packages</file> file to auto-generate +<file>debian/rules</file> and other necessary files in the +<file>debian/</file> subdirectory. + <p> +Note that <package>yada</package> is called "essentially unmaintained" +by it's own maintainer, Charles Briscoe-Smith. As such, it can be +considered deprecated. + </sect1> + + <sect1 id="equivs"> + <heading><package>equivs</package> + <p> +<package>equivs</package> is another package for making packages. It +is often suggested for local use if you need to make a package simply +to fulfill dependencies. It is also sometimes used when making +``meta-packages'', which are packages whose only purpose is to depend +on other packages.</p> + </sect1> + </sect> + + + + <sect id="tools-builders"> + <heading>Package builders</heading> + <p> +The following packages help with the package building process, general +driving <prgn>dpkg-buildpackage</prgn> as well as handling supporting +tasks.</p> + + <sect1 id="cvs-buildpackage"> + <heading><package>cvs-buildpackage</package> + <p> +<package>cvs-buildpackage</package> provides the capability to inject +or import Debian source packages into a CVS repository, build a Debian +package from the CVS repository, and helps in integrating upstream +changes into the repository. + <p> +These utilities provide an infrastructure to facilitate the use of CVS +by Debian maintainers. This allows one to keep separate CVS branches +of a package for <em>stable</em>, <em>unstable</em> and possibly +<em>experimental</em> distributions, along with the other benefits of +a version control system. + </sect1> + + <sect1 id="debootstrap"> + <heading><package>debootstrap</package></heading> + <p> +The <package>debootstrap</package> package and script allows you to +"bootstrap" a Debian base system into any part of your file-system. +By "base system", we mean the bare minimum of packages required to +operate and install the rest of the system. + <p> +Having a system like this can be useful in many ways. For instance, +you can <prgn>chroot</prgn> into it if you want to test your build +depends. Or, you can test how your package behaves when installed +into a bare base system. Chroot builders use this package, see below. + </sect1> + + <sect1 id="pbuilder"> + <heading><package>pbuilder</package></heading> + <p> +<package>pbuilder</package> constructs a chrooted system, and builds a +package inside the chroot. It is very useful to check that a package's +build-dependencies are correct, and to be sure that unnecessary and +wrong build dependencies will not exist in the resulting package.</p> + <p> +A related package is <package>pbuilder-uml</package>, which goes even +further build doing the build within User-mode-linux.</p> + </sect1> + + <sect1 id="sbuild"> + <heading><package>sbuild</package></heading> + <p> +<package>sbuild</package> is another automated builder. It can use +chrooted environments as well. It can be used stand-alone, or as part +of a networked, distributed build environment. As the latter, it is +part of the system used by porters to build binary packages for all +the available architectures. See <ref id="buildd"> for more +information, and <url id="&url-buildd;"> to see the system in +action.</p> + </sect1> + </sect> + + <sect id="uploaders"> + <heading>Package uploaders</heading> + <p> +The following packages help automate or simplify the process of +uploading packages into the official archive.</p> + + <sect1 id="dupload"> + <heading><package>dupload</package></heading> + <p> +<package>dupload</package> is a package and a script to automatically +upload Debian packages to the Debian archive, to log the upload, and +to send mail about the upload of a package. You can configure it for +new upload locations or methods. + </sect1> + + <sect1 id="dput"> + <heading><package>dput</package></heading> + <p> +The <package>dput</package> package and script does much the same +thing as <package>dupload</package>, but in a different way. It has +some features over <package>dupload</package>, such as the ability to +check the GnuPG signature and checksums before uploading, and the +possibility of running <prgn>dinstall</prgn> in dry-run mode after the +upload. + </sect1> + </sect> + + <sect id="tools-maint-automate"> + <heading>Maintenance automation</heading> + <p> +The following tools help automate different maintenance tasks, from +adding changelog entries or signature lines, looking up bugs in Emacs, +to making use of the newest and official use of +<file>config.sub</file>.</p> + + <sect1 id="devscripts"> + <heading><package>devscripts</package></heading> + <p> +<package>devscripts</package> is a package containing wrappers +and tools which are very helpful for maintaining your Debian +packages. Example scripts include <prgn>debchange</prgn> and +<prgn>dch</prgn>, which manipulate your <file>debian/changelog</file> +file from the command-line, and <prgn>debuild</prgn>, which is a +wrapper around <prgn>dpkg-buildpackage</prgn>. The <prgn>bts</prgn> +utility is also very helpful to update the state of bug reports on the +command line. <prgn>uscan</prgn> can be used to watch for new upstream +versions of your packages. The <prgn>debrsign</prgn> can be used to +remotely sign a package prior to upload, which is nice when the +machine you build the package on is different from where your GPG keys +are.</p> + <p> +See the <manref name="devscripts" section="1"> manual page for a +complete list of available scripts.</p> + </sect1> + + <sect1 id="autotools-dev"> + <heading><package>autotools-dev</package></heading> + <p> +Contains best practices for people maintaining packages that use +<prgn>autoconf</prgn> and/or <prgn>automake</prgn>. Also contains +canonical <file>config.sub</file> and <file>config.guess</file> files +which are known to work on all Debian ports.</p> + </sect1> + + <sect1 id="dpkg-repack"> + <heading><package>dpkg-repack</package></heading> + <p> +<prgn>dpkg-repack</prgn> creates Debian package file out of a package +that has already been installed. If any changes have been made to the +package while it was unpacked (e.g., files in <file>/etc</file> were +modified), the new package will inherit the changes.</p> + <p> +This utility can make it easy to copy packages from one computer to +another, or to recreate packages that are installed on your system +but no longer available elsewhere, or to store the current state of a +package before you upgrade it.</p> + </sect1> + + <sect1 id="alien"> + <heading><package>alien</package></heading> + <p> +<prgn>alien</prgn> converts binary packages between various packaging +formats, including Debian, RPM (RedHat), LSB (Linux Standard Base), +Solaris and Slackware packages.</p> + </sect1> + + <sect1 id="debsums"> + <heading><package>debsums</package></heading> + <p> +<prgn>debsums</prgn> checks installed packages against their MD5 sums. +Note that not all packages have MD5 sums, since they aren't required +by Policy.</p> + </sect1> + + <sect1 id="dpkg-dev-el"> + <heading><package>dpkg-dev-el</package></heading> + <p> +<package>dpkg-dev-el</package> is an Emacs lisp package which provides +assistance when editing some of the files in the <file>debian</file> +directory of your package. For instance, when editing +<file>debian/changelog</file>, there are handy functions for +finalizing a version and listing the package's current bugs.</p> + </sect1> + + <sect1 id="dpkg-depcheck"> + <heading><package>dpkg-depcheck</package></heading> + <p> +<prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package> +package, <ref id="devscripts">) +runs a command under <prgn>strace</prgn> to determine all the packages that +were used by the said command. + <p> +For Debian packages, this is useful when you have to compose a +<tt>Build-Depends</tt> line for your new package: running the build +process through <prgn>dpkg-depcheck</prgn> will provide you with a +good first approximation of the build-dependencies. For example: +<example> +dpkg-depcheck -b debian/rules build +</example> + <p> +<prgn>dpkg-depcheck</prgn> can also be used to check for run-time +dependencies, especially if your package uses exec(2) to run other +programs. + <p> +For more information please see <manref name="dpkg-depcheck" section="1">. + </sect1> + + </sect> + + + <sect id="tools-porting"> + <heading>Porting tools</heading> + <p> +The following tools are helpful for porters and for +cross-compilation.</p> + + <sect1 id="quinn-diff"> + <heading><package>quinn-diff</package> + <p> +<package>quinn-diff</package> is used to locate the differences from +one architecture to another. For instance, it could tell you which +packages need to be ported for architecture <var>Y</var>, based on +architecture <var>X</var>. + + <sect1 id="dpkg-cross"> + <heading><package>dpkg-cross</package> + <p> +<package>dpkg-cross</package> is a tool for installing libraries and +headers for cross-compiling in a way similar to +<package>dpkg</package>. Furthermore, the functionality of +<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is +enhanced to support cross-compiling. + </sect1> + + + <sect id="tools-doc"> + <heading>Documentation and information</heading> + <p> +The following packages provide information for maintainers or help +with building documentation. + + <sect1 id="debiandoc-sgml"> + <heading><package>debiandoc-sgml</package></heading> + <p> +<package>debiandoc-sgml</package> provides the DebianDoc SGML DTD, +which is commonly used for Debian documentation. This manual, for +instance, is written in DebianDoc. It also provides scripts for +building and styling the source to various output formats.</p> + <p> +Documentation for the DTD can be found in the +<package>debiandoc-sgml-doc</package> package.</p> + </sect1> + + <sect1 id="debian-keyring"> + <heading><package>debian-keyring</package></heading> + <p> +Contains the public GPG and PGP keys of Debian developers. See <ref +id="key-maint"> and the package documentation for more +information.</p> + </sect1> + + <sect1 id="debview"> + <heading><package>debview</package></heading> + <p> +<package>debview</package> provides an Emacs mode for viewing Debian +binary packages. This lets you examine a package without unpacking +it.</p> + </sect1> + </sect> + +<!-- FIXME: add the following + +questionable: + dbs (referred to above) + dpatch (referred to above) + debarchiver + ucf + dpkg-awk + grep-dctrl + d-shlibs + wajig + magpie + apt-dpkg-ref + apt-show-source + apt-show-versions + pdbv + epm + apt-src + apt-build + +rejected: + debaux: too new, unmaintained? + dh-make-perl: too new, unmaintained? +--> - + </appendix> </book> </debiandoc> @@ -915,6 +4553,7 @@ sgml-indent-step:2 sgml-indent-data:nil sgml-parent-document:nil sgml-exposed-tags:nil +sgml-declaration:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: