<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.162 $">
+ <!entity cvs-rev "$Revision: 1.168 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
<!-- FIXME: rewrites -->
<p>
The procedures discussed within include how to become a maintainer
-(<ref id="new-maintainer">); how to upload new packages (<ref
-id="upload">); how and when to do ports and interim releases of other
-maintainers' packages (<ref id="nmu">); how to move, remove, or orphan
-packages (<ref id="archive-manip">); and how to handle bug reports
-(<ref id="bug-handling">).
+(<ref id="new-maintainer">); how to create new packages
+(<ref id="newpackage">) and how to upload packages (<ref id="upload">);
+how to handle bug reports (<ref id="bug-handling">); how to move,
+remove, or orphan packages (<ref id="archive-manip">); how to port
+packages (<ref id="porting">); and how and when to do interim
+releases of other maintainers' packages (<ref id="nmu">).
<p>
The resources discussed in this reference include the mailing lists
(<ref id="mailing-lists">) and servers (<ref id="server-machines">); a
about licenses, bugs, etc. or discussing the project with others where it
might be useful to have the discussion archived somewhere.
+
<sect id="irc-channels">IRC channels
<p>
Several IRC channels are dedicated to Debian's development. They are mainly
hosted on the <url id="&url-openprojects;" name="freenode"> network
(previously known as Open Projects Network).
The <tt>irc.debian.org</tt> DNS entry is an alias to
-<tt>irc.openprojects.net</tt>.
+<tt>irc.freenode.net</tt>.
<p>
The main channel for Debian in general is <em>#debian</em>. This is a large,
general-purpose channel where users can find recent news in the topic and
Some non-English developers' channels exist as well, for example
<em>#debian-devel-fr</em> for
French speaking people interested in Debian's development.
+ <p>
+Channels dedicated to Debian also exist on other IRC networks, notably on
+the <url name="Open and free technology community (OFTC)"
+id="http://www.oftc.net/"> IRC network.
<sect id="doc-rsrcs">Documentation
<p>
The Developers Database, at <url id="&url-debian-db;">, is an LDAP
directory for managing Debian developer attributes. You can use this
-resource to search the list of Debian developers. For information on
-keeping your entry the developer database up-to-date, see <ref
-id="user-maint">. Part of this information is also available through
+resource to search the list of Debian developers.
+Part of this information is also available through
the finger service on Debian servers, try
<prgn>finger yourlogin@db.debian.org</prgn> to see what it reports.
<p>
-This database lets you register some other information like public SSH
-keys that will be automatically installed on the official debian machines
-or like *.debian.net DNS entry. Those features are documented
-at <url id="&url-debian-db-mail-gw;">.
+Developers can <url name="log into the database" id="&url-debian-db-login;">
+to change their debian-private list subscription, their personal
+information, to mark themselves on vacation, etc.
+For more information on keeping your entry the developer database
+up-to-date, please see <ref id="user-maint">.
+ <p>
+One can also submit their SSH keys to be used for authorization on the
+official Debian machines, and even add new *.debian.net DNS entries.
+Those features are documented at <url id="&url-debian-db-mail-gw;">.
<sect id="archive">The Debian archive
package licenses of the packages in <em>non-free</em> and include as
many on the CD-ROMs as he's allowed to. (Since this varies greatly from
vendor to vendor, this job can't be done by the Debian developers.)
+ <p>
+Note also that the term "section" is also used to refer to categories
+which simplify the organization and browsing of available packages, e.g.
+<em>admin</em>, <em>net</em>, <em>utils</em> etc. Once upon a time, these
+sections (subsections, rather) existed in the form of subdirectories within
+the Debian archive. Nowadays, these exist only in the "Section" header
+fields of packages.
<sect1>Architectures
pages">.
-<!-- <sect1>Subsections
- <p>
-The sections <em>main</em>, <em>contrib</em>, and <em>non-free</em>
-are split into <em>subsections</em> to simplify the installation
-process and the maintenance of the archive. Subsections simply exist to
-simplify the organization and browsing of available packages. The
-<url id="&url-debian-policy;" name="Debian Policy Manual"> gives
-the authoritative list of subsections.
-
- <p>
-Note however that with the introduction of package pools (see the top-level
-<em>pool/</em> directory), the subsections in the form of subdirectories
-will eventually cease to exist. They will be kept in the packages' `Section'
-header fields, though. -->
<sect1>Packages
<p>
made, a special script is called to ask all the primary mirrors to update
themselves.
<p>
-All debian developers have write access to the <file>unchecked</file>
+The archive maintenance software will also send the OpenPGP/GnuPG signed
+<file>.changes</file> file that you uploaded to the appropriate mailing
+lists. If a package is released with the <tt>Distribution:</tt> set to
+`stable', the announcement is sent to &email-debian-changes;.
+If a package is released with <tt>Distribution:</tt> set to `unstable'
+or `experimental', the announcement will be posted to
+&email-debian-devel-changes; instead.
+ <p>
+All Debian developers have write access to the <file>unchecked</file>
directory in order to upload their packages, they also have that access
to the <file>reject</file> directory in order to remove their bad uploads
or to move some files back in the <file>unchecked</file> directory. But
why you can not remove an upload once it has been accepted.
<sect1 id="delayed-incoming">Delayed incoming
- <p>
+ <p>
The <file>unchecked</file> directory has a special <file>DELAYED</file>
subdirectory. It is itself subdivided in nine directories
called <file>1-day</file> to <file>9-day</file>. Packages which are uploaded in
easily upload a package in one of the delayed directories:
<example>DELAY=5 dupload --to delayed <changes-file></example>
+
<sect id="testing">
<heading>The "testing" distribution</heading>
<p>
id="&url-testing-maint;"> for more information. It also includes
answers to some of the frequently asked questions.
+
<sect id="pkg-info">Package information
<p>
This chapter contains information related to creating, uploading,
maintaining, and porting packages.
- <sect id="upload">Package uploads
- <sect1>New packages
+ <sect id="newpackage">New packages
<p>
If you want to create a new package for the Debian distribution, you
should first check the <url id="&url-wnpp;" name="Work-Needing and
better feel of what is going on, and what is new, in the project.
</list>
- <sect1 id="changelog-entries">
- <heading>Adding an entry to <file>debian/changelog</file></heading>
+
+ <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
and <ref id="dpkg-dev-el">.
+ <sect id="upload">Package uploads
+
+ <p>
+When a package is uploaded to the Debian archive, it must be accompanied by
+a <tt>.changes</tt> control file, which gives directions to the archive
+maintenance software for its handling. This is generated by
+<prgn>dpkg-genchanges</prgn> during the normal package build process.
<sect1 id="upload-checking">Checking the package prior to upload
<p>
</list>
- <sect1>Generating the changes file
- <p>
-When a package is uploaded to the Debian FTP archive, it must be
-accompanied by a <file>.changes</file> file, which gives directions to the
-archive maintainers for its handling. This is usually generated by
-<prgn>dpkg-genchanges</prgn> during the normal package build process.
+ <sect1>Layout of the source files
<p>
-The changes file is a control file with the following fields:
+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>
-&control-file-fields;
+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>
-All of these fields are mandatory for a Debian upload. See the list
-of control fields in the <url id="&url-debian-policy;" name="Debian
-Policy Manual"> for the contents of these fields. You can close bugs
-automatically using the <tt>Description</tt> field, see <ref
-id="upload-bugfix">.
-
-
- <sect2>The original source tarball
+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
byte-for-byte identical with the one already in the archive.
- <sect2 id="upload-dist">Picking a distribution
+ <sect1 id="upload-dist">Picking a distribution
<p>
-The <tt>Distribution</tt> field, which originates from the first line of
-the <file>debian/changelog</file> file, indicates which distribution the
-package is intended for.
+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>. Actually, there are two other possible distributions:
-`stable-security' and `testing-security'. However they are used by the
-security team; do not upload there without their agreement.
+`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
In particular, it never makes sense to combine the <em>experimental</em>
distribution with anything else.
-
- <sect3 id="upload-stable">Uploading to <em>stable</em>
+ <sect2 id="upload-stable">Uploading 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
<em>stable</em>, because otherwise the package won't be considered for
inclusion.
- <sect3 id="upload-t-p-u">Uploading to <em>testing-proposed-updates</em>
+ <sect2 id="upload-t-p-u">Uploading 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
newer development version in unstable), you may use it but it is recommended to ask
the authorization of the release manager before.
+
<sect1 id="uploading">Uploading a package
<sect2 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
anonymous FTP to <url id="&url-upload-jp;">.
-
- <sect1 id="upload-announce">Announcing package uploads
- <p>
-When a package is uploaded, an announcement should be posted to one of
-the ``debian-changes'' lists. This is now done automatically by the archive
-maintenance software when it runs (usually once a day). You just need to use
-a recent <package>dpkg-dev</package> (>= 1.4.1.2). The mail generated by
-the archive maintenance software will contain the OpenPGP/GnuPG signed
-<file>.changes</file> files that you uploaded with your package.
-Previously, <prgn>dupload</prgn> used to send those announcements, so
-please make sure that you configured your <prgn>dupload</prgn> not to
-send those announcements (check its documentation and look for
-``dinstall_runs'').
- <p>
-If a package is released with the <tt>Distribution:</tt> set to
-`stable', the announcement is sent to &email-debian-changes;. If a
-package is released with <tt>Distribution:</tt> set to `unstable',
-or `experimental', the announcement will be
-posted to &email-debian-devel-changes; instead.
-
<sect1 id="upload-notification">
<heading>Notification that a new package has been installed</heading>
<p>
section the package was inserted into. If there is a disparity, you
will receive a separate email notifying you of that. Read on below.
- <sect2 id="override-file">The override file
+ <sect1 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
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">, &file-bts-mailing;, and
-&file-bts-info;.
-
+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="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.
+ <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="nmu-terms">Terminology
+ <sect1>Monitoring bugs
<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.
+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>
-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.
+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>
-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.
+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>
-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.
+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="nmu-who">Who can do an NMU
+ <sect1 id="upload-bugfix">When bugs are closed by new uploads
<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.
+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
- <sect1 id="nmu-when">When to do a source NMU
+ * 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>
-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">).
+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>
-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="upload-checking">).
-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.
+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>.
- <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.
+ <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="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="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.
- <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>
+ <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)
- <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.
+ <item>Any information needed for the advisory (see <ref
+ id="bug-security-advisories">)
+</list>
- <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="upload-dist">. Just as described in
-<ref id="uploading">, a normal changes file, etc., will be built. In
-fact, all the prescriptions from <ref id="upload"> apply.
- <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.
+ <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:
- <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">).
+<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:
- <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.
+<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>
- <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.
+<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).
-<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. 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.
- <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>
+<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.
- <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="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:
- <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''.
+<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).
- <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.
+When packaging the fix, keep the following points in mind:
-<!--
-FIXME: commented out until I can work out how to upload to testing directly
+<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!
- 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.
+ <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.
- <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>
+ <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>).
- <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>
+ <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.
- <sect2>
- <heading>Porter tools</heading>
- <p>
-Descriptions of several porting tools can be found in <ref
-id="tools-porting">.</p>
- </sect2>
+ <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="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>
+ <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="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>
<sect id="archive-manip">
<heading>Moving, removing, renaming, adopting, and orphaning
they will continue to receive the bugs during that time.
- <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">.
+ <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>Monitoring bugs
+
+ <sect1 id="kind-to-porters">Being kind to porters
<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>.
+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>
-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;.
+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>
-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.
+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. 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.
+ <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="bug-answering">Responding to bugs
+
+ <sect1 id="porter-guidelines">Guidelines for porter uploads
<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>).
+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>
-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">.
+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>
-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.
+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>.
- <sect1 id="bug-housekeeping">Bug housekeeping
+ <sect2 id="binary-only-nmu">
+ <heading>Recompilation or binary-only NMU</heading>
<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="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:
+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''.
-<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)
+ <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.
- <item>Any fixed packages that you have prepared yourself (send only
- the <tt>.diff.gz</tt> and <tt>.dsc</tt> files)
+<!--
+FIXME: commented out until I can work out how to upload to testing directly
- <item>Any information needed for the advisory (see <ref
- id="bug-security-advisories">)
+ 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.
-</list>
- <sect2 id="bug-security-confidentiality">Confidentiality
+ <sect1 id="porter-automation">
+ <heading>Porting infrastructure and automation</heading>
<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:
+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>
-<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.
+ <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>
- <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>
+ <sect2>
+ <heading>Porter tools</heading>
+ <p>
+Descriptions of several porting tools can be found in <ref
+id="tools-porting">.</p>
+ </sect2>
-<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).
+ <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>
-<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.
+ <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.
- <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:
+ <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.
-<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).
+ <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.
-When packaging the fix, keep the following points in mind:
+ <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 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 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="upload-checking">).
+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.
- <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.
+ <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.
- <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>).
+ <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'.
- <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="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="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.
+ <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.
-<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.
+ <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="upload-dist">. Just as described in
+<ref id="uploading">, a normal changes file, etc., will be built. In
+fact, all the prescriptions from <ref id="upload"> apply.
+ <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="upload-bugfix">When bugs are closed by new uploads
+ <sect1 id="ack-nmu">Acknowledging an NMU
<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.
+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>
-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
+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">).
- * 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:
+ <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>
- /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
+Uploaders: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org>
</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>.
-
+</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>
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. While <prgn>which</prgn> is an acceptable alternative, since
+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, although that is probably not something
-that will cause a problem.
+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">
~ianmdlvl / developers-reference.git / blobdiff