+ <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>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.debian.org</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.debian.org</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.debian.org</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.debian.org</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 bot 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>
+If you fix a bug in your packages, it is your responsibility as the
+package maintainer to close the bug when it has been fixed. However,
+you should not close the bug until the package which fixes the bug has
+been accepted into the Debian archive. Therefore, once you get
+notification that your updated package has been installed into the
+archive, you can and should close the bug in the BTS.
+ <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 is what is
+used:
+<example>
+ /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
+</example>
+
+The author prefers the <tt>closes: #<var>XXX</var></tt> syntax, as
+one of the most concise and easiest to integrate with the text of the
+<file>changelog</file>.
+ <p>
+If you happen to mistype a bug number or forget one in the changelog file,
+don't hesitate to undo any damage the error caused. To reopen wrongly closed
+bugs, send an <tt>reopen <var>XXX</var></tt> command in the bug tracking
+system's control bot. To close any remaining bugs that were fixed by your
+upload, email the <file>.changes</file> file to
+<email>XXX-done@bugs.debian.org</email>, where <var>XXX</var> is your
+bug number.
+ <p>
+Bear in mind that it is not obligatory to close bugs using the changelog
+like described above -- if you simply want to close bugs that don't have
+anything to do with an upload of yours, do it simply by emailing an
+explanation to <email>XXX-done@bugs.debian.org</email>.
+Do <strong>not</strong> close bugs in the changelog entry of a version
+if the said version of the package doesn't have anything to do with the bug.
+ <p>
+For general information on what to put in the changelog files, please
+refer to <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>).