-<!doctype debiandoc system [
-<!-- include version information so we don't have to hard code it
- within the document
- -->
-<!entity % versiondata SYSTEM "version.ent"> %versiondata;
-]>
-
-<!--
- Debian GNU/Linux Developer's Reference.
- Copyright (C)1997,1998 Christian Schwarz;
- released under the terms of the GNU
- General Public License, version 2 or (at your option) any later.
- -->
+<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
+ <!-- include version information so we don't have to hard code it
+ within the document -->
+ <!entity % versiondata SYSTEM "version.ent"> %versiondata;
+ <!-- common, language independant entities -->
+ <!entity % commondata SYSTEM "common.ent" > %commondata;
-<!--
-
- Topics to be included someday:
- - bugs in upstream versions should be reported upstream!
-
- -->
+ <!-- CVS revision of this document -->
+ <!entity cvs-rev "$Revision: 1.199 $">
+ <!-- if you are translating this document, please notate the CVS
+ revision of the developers reference here -->
+ <!--
+ <!entity cvs-en-rev "X.YY">
+ -->
-<book>
+ <!-- -->
+ <!entity FIXME "<em>FIXME:</em> ">
-<title>Debian Developer's Reference
-<author>Christian Schwarz <email/schwarz@debian.org/
-<author>based on earlier documents by Ian Jackson <email/ijackson@gnu.ai.mit.edu/
-<version>version &version;, &date;
+]>
+<debiandoc>
+ <book>
+ <title>Debian Developer's Reference
-<copyright>Copyright ©1997,1998 Christian Schwarz.
-<p>
+ <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>
+ <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
Free Software Foundation; either version 2, or (at your option) any
later version.
-<p>
-
+ <p>
This is distributed in the hope that it will be useful, but
<em>without any warranty</em>; without even the implied warranty of
merchantability or fitness for a particular purpose. See the GNU
General Public License for more details.
-<p>
+ <p>
+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;.
-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
-<tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also obtain it
-by writing to the Free Software Foundation, Inc., 59 Temple Place -
-Suite 330, Boston, MA 02111-1307, USA.
-<p>
+ <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.
- <toc sect>
+<!-- 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.
- <chapt>Applying to Become a Maintainer<p>
+
+ <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 <prgn/debian-devel/ 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, as 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/ in the
- <ftppath>/pub/debian/README.non-US</> 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.
- <p>
-
- <sect>Registering as a Debian developer
- <p>
-
- Before you decide to work in the Debian Project you have to
- read the ``Debian Social Contract'' (available on
- <tt/www.debian.org/).
- <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 master and to be subscribed to
- debian-private (the developers-only mailing list). It should
- contain your PGP or RSA public key (extracted using `pgp
- -kxa', in the case of PGP) for the database of keys which is
- distributed on the FTP server
- (<tt>doc/debian-keyring.tar.gz</tt>). 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
- master (seven characters or less), as well as the E-mail
- address at which you'd prefer to be subscribed to
- debian-private (typically this will be either your primary
- mail address or your new debian.org 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.
- <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.
- <p>
-
- <sect>Debian Mentors
- <p>
-
- There is a mailing list called <tt/debian-mentors/ which has
- been set up for newbie maintainers who seek help with
- initial packaging and other developer-related issues.
- <p>
- Every new developer is invited to subscribe to that list
- (see <ref id="mailing-lists"> for details).
- <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.
- <p>
-
-
- <chapt>Internet Servers<p>
-
- <sect id="mailing-lists">Mailing lists<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.
- <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: <tt/debian-devel/,
- <tt/debian-policy/, <tt/debian-user/, <tt/debian-announce/,
- <tt/debian-devel-announce/.
- <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.
- <p>
-
- <sect>The master server
- <p>
-
- <sect>The FTP servers
- <p>
-
- <sect>The WWW servers
- <p>
-
- <chapt>The Debian Archive<p>
-
- <sect>Overview
- <p>
-
- The Debian GNU/Linux distribution consists of a lot of
- Debian packages (<tt/.deb/'s, currently more than 1000) and
- a few additional files (documentation, installation disk
- images, etc.).
- <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>
+ <sect id="getting-started">Getting started
+ <p>
+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>
- 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</>.
+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>
- 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).
- <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.).
+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>
- The <em/binary/ and <em/source/ directories are divided
- further into <em/sub-sections/.
+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.
+
+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>
+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>
-
- <sect>Sections
+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>
+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.)
- The <em>main 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.
<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.)
- <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.
+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>
- Packages in the <em>contrib</> section have to apply to
- the DFSG, but fail other requirements.
- <p>
- (The Debian Policy Manual contains a more exact definition
- of the three sections. This is just meant to be 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/ and
- <em/contrib/ sections, one can avoid any legal risks,
- since some packages in the <em/non-free/ 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/
- 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.)
- <p>
-
- <sect>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, DEC Alphas, SUN Sparcs,
- M68000 machines (like Atari and Amiga), MIPS, and
- PowerPC.
- <p>
- Debian GNU/Linux 1.3 is only available for Intel
- platforms. One of the goals for Debian 2.0 is to support
- some of the other architectures, too.
- <p>
-
- <sect>Sub sections
- <p>
-
- The sections <em/main/, <em/contrib/, and <em/non-free/ are
- split into <em/sub sections/, to simplify the installation
- process and the maintainance of the archive.
- <p>
-
- <sect>Packages
- <p>
-
- There are two types of Debian packages, namely <em/source/
- and <em/binary/ packages.
- <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.
+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>
- 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.
+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>
- 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.
+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>
- The <tt/.dsc/ lists all components of the source package
- together with checksums (md5sums) and some additional info
- about the package (maintainer, version, etc.).
+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.
- <sect>Distribution directories
+
+ <sect id="mentors">Debian mentors and sponsors
+ <p>
+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>
+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>
+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">.
- 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/.
+
+ <chapt id="developer-duties">Debian Developer's Duties
+
+ <sect id="user-maint">Maintaining your Debian information
<p>
- There is always a distribution called <em/stable/ and one
- called <em/unstable/. This reflects the development process
- of the Debian project:
+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">.
+
+
+
+ <sect id="key-maint">Maintaining your public key
<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/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.''
+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>
- After about two months 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.'')
+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>
- 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.
+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>
- This development cycle is based on the assumption, that the
- once `unstable' distribution finally becomes `stable' after
- passing one month of testing. Unfortunately, a few bugs
- still remain--that's why the stable distribution is updated
- every few weeks. However, these updates are tested very
- carefully and have to be acknowledged individually to reduce
- the risk of introducing new bugs.
+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>
- Note, that development is continued during the ``freeze''
- period, since a new ``unstable'' distribution will be
- created at that time.
+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>
- In summary, there is always a <em/stable/ and an
- <em/unstable/ distribution available and the <em/frozen/
- distribution shows up for a month from time to time.
+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>Release code names
+
+ <sect id="inform-vacation">Going on vacation gracefully
<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/, etc.
+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>
- Since the Debian has an open development (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!).
+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>
- 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.)
+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>
- 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.
- <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.
- <p>
-
- <chapt>Package uploads<p>
-
- <sect>Announcing new packages
- <p>
- If you want to create a new package for the Debian
- distribution, you have to send a short email to
- <em/debian-devel/ describing your plans before you upload
- the new package.
- <p>
- This has the following advantages:
-
- <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
- <p>
- <item>It lets other people thinking about working on the
- package know that there already is a volunteer, and
- efforts may be shared
- <p>
- <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 debian-devel-changes by default
- <p>
- <item>It is helpful to the people who live off unstable
- (and form our first line of testers); we should
- encourage these people
- <p>
- <item>I think the announcements gives us a better feel of
- what is going on, and what is new, in the project.
- <p>
- <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
- <p>
- <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>
-
- <sect>Uploading a package
+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>
+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.
- <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>
+ <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>
+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).
- 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>
- <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>
+ <sect>Retiring
+ <p>
+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>
- 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.
+ <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>
+The mailing list server is at <tt>&lists-host;</tt>.
+ <p>
+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>
+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;.
+
+ <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>
+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 id="irc-channels">IRC channels
+ <p>
+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>
+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>
+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>
+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>
+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>
+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>
+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.
+
+
+ <sect id="doc-rsrcs">Documentation
+ <p>
+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.
+
+
+ <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.
+
+ <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>.
+
+ <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">.
+
+ <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">.
+
+ <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 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>
+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.
+
+
+ <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>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.).
+
+
+ <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.
+
+
+ <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">.
+
+
+
+ <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>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).
+
+
+ <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>Transferring the files to master
+ <sect2 id="experimental">Experimental
<p>
- To upload a package, you need a personal account on the
- master server. Just log in via ftp and transfer the
- files to
- `<tt>/home/Debian/ftp/private/project/Incoming</tt>.'
- (You cannot upload to Incoming on master using anonymous
- FTP--you must use your user-name and password.)
+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>
- You may also find the Debian package '<tt>dupload</tt>'
- useful in uploading new packages to master. See the
- '<tt>dupload</tt>' documentation for more information.
- <p>
-
- <sect1>Uploads via Chiark
- <p>
- If you have a slow network connection to the master
- system, there are two alternatives: You can upload files
- to Incoming via a cron-driven upload queue in Europe on
- ftp.chiark.greenend.org.uk. For details connect to chiark
- using anonymous FTP and read
- <tt>/pub/debian/private/project/README.how-to-upload</tt>.
- <p>
- The program <tt/dupload/ support uploads to chiark, please
- refer to the documentation that comes with the program,
- for details.
- <p>
-
- <sect1>Uploads via Erlangen
- <p>
- Another cron-driven upload queue is available in Germany:
- Just upload the files via anonymous FTP to
- <tt>ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue</>.
- <p>
- The upload must be a complete Debian upload, as you would
- put it into master's 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
- *your* e-mail address. The address found there is used for
- all replies, just as on master.
- <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.
- <p>
- The program <tt/dupload/ support uploads to erlangen,
- please refer to the documentation that comes with the
- program, for details.
- <p>
-
- <sect1>Uploading to the non-us server
- <p>
- To upload a package to the <em/non-us/ server you just
- have to transfer the files via anonymous ftp to
- <tt>ftp://nonus.debian.org/pub/debian-non-US/Incoming</tt>.
- Note, that the <tt>.changes</tt> file must have a valid
- PGP signature from one of the keys of the developers
- keyring.
- <p>
-
- <sect>Announcing package uploads
- <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 <prgn/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.
- <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/.
- <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.
- <p>
-
- <sect>Interim releases
- <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 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. If the
- non-maintainer upload fixes some bugs, the bug reports
- should not be closed. 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. This way, the maintainer and other
- people will get notified about that.
- <p>
- The normal maintainer should do at least one of
- <list compact>
- <item> apply the diff,
+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>
+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>
+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>
+An alternative to <em>experimental</em> is to use your personal web space
+on <tt>people.debian.org</tt>.
- <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>
+ <sect1 id="codenames">Release code names
+ <p>
+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>
+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>
+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>
+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 id="mirrors">Debian mirrors
+ <p>
+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>
+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>
+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 id="incoming-system">
+ <heading>The Incoming system
+ <p>
+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>
+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>
+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>
+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>
- In addition, the normal maintainer should <em/always/
- include an entry in the changelog file documenting the
- non-maintainer upload.
+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.
+
+ <sect1 id="delayed-incoming">Delayed incoming
+ <p>
+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>
+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 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>
+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.
+
+
+ <sect id="pkg-info">Package information
+ <p>
+
+ <sect1 id="pkg-info-web">On the web
+ <p>
+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>
+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>
+<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 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>
+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.
+
+ <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>
+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>Maintainer changes
+ <sect id="ddpo">Developer's packages overview
<p>
- Periodically, a listing of packages in need of new
- maintainers will be sent to the <tt>debian-devel</>
- list. This list is also available at
- <ftpsite>ftp.debian.org</> in
- <ftppath>/debian/doc/package-developer/prospective-packages.html</>
- If you wish to take over maintenance of any of those
- packages, or if you can no longer maintain the packages you
- have, or you simply want to know if any one is working on a
- new package, send a message to
- <email/override-change@debian.org/.
+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>
- 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.
+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.
- <chapt>Handling bug reports<p>
- <sect>Reporting lots of bugs at once
+ <sect id="newpackage">New packages
<p>
- If you report more then 10 bugs on the same topic at once,
- it is recommended that you send a message to 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 prevent the situation where
- several maintainers start filing the same bug report
- simultaneously.
+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>
- Note, that when sending lots of bugs on the same subject,
- you should send the bug report to
- <tt/maintonly@bugs.debian.org/ so that the bug report is not
- forwarded to the bug distribution mailing list.
+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>
-
-</book>
+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>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+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:
+-->
~ianmdlvl / developers-reference.git / blobdiff