+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.
+
+ <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 package bugs
+ <p>
+Often as a package maintainer, you find bugs in other packages or else
+have bugs reported to your packages which need to be reassigned. The
+<url id="&url-bts-control;" name="BTS instructions"> can tell you how
+to do this. Some information on filing bugs can be found in <ref
+id="submit-bug">.
+
+ <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 (examples are
+the <package>vim-*</package> packages) 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> (vanilla approach) 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 configure
+options. The <package>vim</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-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 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.
+
+
+
+ <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, but "GTK+" is
+probably not. Try not to assume any knowledge at all. If you must
+use technical terms, introduce them.
+ <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".
+
+
+ <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). Imagine that the synopsis is combined
+with the package name in the following way:
+
+<example>The <var>package-name</var> is a <var>synopsis</var>.</example>
+ <p>
+If the package name is an acronym, it is sometimes useful to expand
+the acronym. For instance, the synopsis for <package>vim</package> is
+"Vi IMproved - enhanced vi editor".
+
+
+ <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.
+It is recommended to use two spaces after full stops in sentences. We
+realize this is an American style rather than European, but it is
+additionally helpful in creating visual space in fixed-width fonts.
+ <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 empty.
+ <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).
+-->
+
+
+ <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 developer's packages improves the quality of
+Debian.
+ <p>
+Try to submit the bug from a normal user account at which you are
+likely to receive mail. Do not submit bugs as root.
+ <p>
+Make sure the bug is not already filed against a package. Try to do a
+good job reporting a bug and redirecting it to the proper location.
+For extra credit, you can go through other packages, merging bugs
+which are reported more than once, or setting bug severities to
+`fixed' when they have already been fixed. Note that when you are
+neither the bug submitter nor the package maintainer, you 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:<your-email-addr></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:
+ 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?
+-->