<!--
TODO:
- bugs in upstream versions should be reported upstream!
- - porter instructions - - volunteers needed for this x86-centric
- maintainer!
- add information on how to get accounts on different architectures
- - talk about CVS access
+ - talk about CVS access, other ways to submit problems
+ - add information on how you can contribute w/o being an official
+ developer
+ - "official port maintainer" ? (cf. glibc-pre2.1)
-->
<book>
<title>Debian Developer's Reference
- <author>Adam P. Harris, current maintainer <email/aph@debian.org/
+ <author>Adam Di Carlo, current maintainer <email/aph@debian.org/
<author>Christian Schwarz <email/schwarz@debian.org/
<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
<version>ver. &version;, &date;
<copyright>
<copyrightsummary><!-- this tag not working right -->
- <p>
-Copyright ©1998 Adam P. Harris. Copyright ©1997,1998
-Christian Schwarz.
+copyright ©1998 Adam Di Carlo, ©1997,1998
+Christian Schwarz</copyrightsummary>
<p>
This manual is free software; you may redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
HTTP) servers can be found at <url
id="http://www.debian.org/distrib/ftplist">. More information
concerning Debian mirrors can be found at <url
-id="http://www.debian.org/devel/mirror/">. This useful page includes
+id="http://www.debian.org/mirror">. This useful page includes
information and tools which can be helpful if you are interested in
setting up your own mirror, either for internal or public access.
<p>
not, to different degrees; as such, they are not officially part of
Debian.
<p>
-Every package in the main section must fully comply with the <url
+Every package in the main section must fully comply with the <!-- work
+around quoting of fragment idendifiers bug <url
id="http://www.debian.org/social_contract#guidelines" name="Debian
-Free Software Guidelines"> (DFSG) and with all other policy
-requirements as described in the <url
-id="http://www.debian.org/doc/debian-policy/" name="Debian Policy
-Manual">. The DFSG is our definition of ``free software.'' Check out
-the Debian Policy Manual for details.
+Free Software Guidelines"> --> <url
+id="http://www.debian.org/social_contract" name="Debian Free Software
+Guidelines"> (DFSG) and with all other policy requirements as
+described in the <url id="http://www.debian.org/doc/debian-policy/"
+name="Debian Policy Manual">. The DFSG is our definition of ``free
+software.'' Check out the Debian Policy Manual for details.
<p>
The packages which do not apply to the DFSG are placed in the
<em/non-free/ section. These packages are not considered as part of
<p>
Debian GNU/Linux 1.3 is only available as <em>i386</em>. Debian 2.0
supports <em>i386</em> and <em>m68k</em> architectures. The next
-version of Debian is likely to also support all these, in addition to
-<em>alpha</em>, <em>ppc</em>, and <em>sparc</em> architectures.
+version of Debian is likely to support <em>i386</em>, <em>m68k</em>,
+<em>alpha</em>, and possibly <em>ppc</em> and <em>sparc</em>
+architectures.
<sect>Subsections
The sections <em/main/, <em/contrib/, and <em/non-free/ are split into
<em/subsections/ to simplify the installation process and the
maintainance of the archive. Subsections are not formally defined,
-excepting perhaps for the `base' subsection. Subsections exist simply
+excepting perhaps the `base' subsection. Subsections exist simply
to simplify the organization and browsing of available packages.
Please check the current Debian distribution to see which sections are
available.
-
+<p>
<sect>Packages
the keys of the developers key-ring.
- <sect>Announcing package uploads
+ <sect id="upload-announce">Announcing package uploads
<p>
When a package is uploaded an announcement should be posted to one of
the ``debian-changes'' lists. The announcement should give the (source)
<package/ftp.debian.org/.
<p>
For more information about <em/override files/, see
-<manref name="dpkg-scanpackages" section="8">,
+<manref name="dpkg-scanpackages" section="8"/>,
<tt>/usr/doc/debian/bug-log-mailserver.txt</tt>, and
<tt>/usr/doc/debian/bug-maint-info.txt</tt>.
- <sect id="nmu">Interim releases
- <p>
+
+ <chapt id="nmu">Non-Maintainer Uploads (NMUs) and Porters
+
+ <p>
Under certain circumstances it is necessary for someone other than the
-usual package maintainer to make a release of a package. For example,
-a porter for another architecture may have to make some small changes
-to the source package and does not wish to wait with uploading their
-release until the main maintainer has incorporated the patch, or a
-serious security problem or bug may have come to light requiring
-immediate attention.
+usual 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, do
+binary NMUs as part of their normal porting activity. Sometimes,
+Debian developers do NMUs in order to fix a serious security problem
+or a crippling bug, especially 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.
+
+
+<sect id="nmu-who">Who can do an NMU
+ <p>
+Only official Debian maintainers can do NMUs.
+Non-developers, however, are encouraged to download the source
+package and start hacking on it to fix problems. Maintainers almost
+always appreciate quality patches and bug reports. Of course there
+are many other ways that not-yet-official volunteers can help.
+<!-- TODO: link to section talking about how non-maintainers can still
+ contribute -->
+
+<sect id="nmu-when">When to do an NMU
<p>
When a security bug is detected a fixed package should be uploaded as
soon as possible. In this case, the Debian Security Managers should
if he/she cannot be reached in time, the Security Manager may upload a
fixed package.
<p>
-When someone other than the usual maintainer releases a package they
-should add a new component to the <var/debian-revision/ component of
-the version number--that is, the portion after the (last) hyphen.
-This extra component will start at `1'. This is to avoid
-`stealing' one of the usual maintainer's version numbers, possibly
-disrupting their work. If there is no <var/debian-revision/ component
-in the version number then one should be created, starting at `1'.
+During the release freeze (see <ref id="upload-frozen">), NMUs which
+fix important 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.
<p>
+Bug fixes to unstable by non-maintainers are also acceptable, but only
+as a last resort. Try the following steps first, and if they don't
+work, it is ok to do an NMU:
+ <p>
+<list>
+ <item>
+Make sure that the package bug is in the Debian BTS. If not, submit a
+bug.
+ <item>
+Email the maintainer, and offer to help fix the package bug. Give it a
+few days.
+ <item>
+Go ahead and fix the bug, submitting a patch to the right bug in
+the Bug Tracking System.
+ <item>
+Wait a couple of weeks for a response.
+ <item>
+Email the maintainer, asking if it is ok to do an NMU.
+ <item>
+Wait a couple of weeks for a response.
+ <item>
+Double check that your patch doesn't have any unexpected side effects.
+Build the package and test it as discussed in <ref id="upload-checking">.
+ </list>
+
+ <sect1>When to do an NMU if you are a porter
+ <p>
+Porters who have to patch the source package in order to get the
+package to compile need to follow these steps as well, although their
+window of time that they should wait is smaller, since they deal with
+a high quantity of packages.
+ <p>
+Again, the situation will vary depending on the distribution they are
+uploading to. Crucial fixes (i.e., changes need to get a source package
+to compile) can be uploaded with <em/no/ 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 one variation.
+If you need to alter the source of a package in order to get a
+released port of Debian to compile, the bug you submit to the BTS
+should be of severity `important' or greater. This ensures that a
+single source package can be used to compile every supported Debian
+architecture.
+ <p>
+An acceptable waiting period -- the time between when the bug is
+submitted to the BTS and when it is ok to do an NMU -- is ten days
+for porters working on the unstable distribution.
+ <p>
+Try to avoid patches which simply kluge around bugs in the current
+version of the compile environment, kernel, or libc. Sometimes
+that can't be helped. If you have to kluge around compilers bugs and
+the like, make sure you <tt>#ifdef</tt> your work properly; also,
+document your kluge 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.
+
+
+<sect id="nmu-guidelines">How to do an NMU
+
+This section applies to NMUs, but not, necessarily, to porters.
+A distinction is made between a <em/port/ and an <em/NMU/. An NMU is
+a fix to a problem with an existing version of a package in an
+archive. A port is a recompile of a specific revision of a package to
+another port, such that people running the target architecture have
+access to the port.
+ <p>
+The following applies to porters insofar as they are playing the dual
+role of being both NMU bug-fixers, and porters. So, if a porter has
+to change the Debian source archive, automatically their upload is an
+NMU and is subject to its rule. If a porter is simply uploading a
+port, the rules are different; see <ref id="porter-guiddelines">.
+
+<sect1 id="nmu-version">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 actually work.
+ <p>
+If you are doing a non-maintainer upload (NMU), you should add a new
+minor version number to the <var/debian-revision/ 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 <tt>foo_1.1-3.dsc</tt>. 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
+<tt>foo_1.1-3.1.dsc</tt>.
+ <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 made by an NMU.
+ <p>
+If there is no <var/debian-revision/ 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/
switch to force the build system to pick up the new source package
(normally it only looks for Debian revisions of '0' or '1').
<p>
+Remember, porters who are simply recompiling a package for a different
+architecture do not need to renumber. Porters should use new NMU
+version numbers if and only if they actually have to modify the source
+package in some way.
+
+<sect1 id="nmu-changelog">NMUs must create a changelog entry
+ <p>
+A non-maintainer doing an 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.
+
+<sect1 id="nmu-patch">NMUs must send patches, if any, to the BTS
+ <p>
Maintainers other than the usual package maintainer should make as few
changes to the package as possible, and they should always send a
-unified context diff (<tt/diff -u/) detailing their changes to the bug
-tracking system properly flagged with the correct package so that the
-usual maintainer is kept aware of the situation.
- <p>
-If the non-maintainer upload (as known as an ``NMU'') fixes some
-existing bugs, the bug reports should not be closed. Technically,
-only the official package maintainer or the original bug submitter are
-allowed to close bugs. However, the person making the non-maintainer
-release should send a short message to the bug tracking system to all
-the fixed bugs explaining that they have been fixed. Using
+patch as a unified context diff (<tt/diff -u/) detailing their
+changes, if any, to the bug tracking system.
+ <p>
+What if you are simply recompiling the package? In this case, the
+process is different for porters than it is for non-porters, as
+mentioned above. If you are doing an NMU that simply requires a
+recompile (i.e., a new shared library is available to be linked
+against, a bug was fixed in <package/debhelper/), there <em/will/ be a
+changelog entry; therefore, there will be a patch.
+ <p>
+If the NMU (non-maintainer upload) fixes some existing bugs, the bugs
+which are fixed need to be <em/notified/ but not actually <em/closed/
+by the non-maintainer. Technically, only the official package
+maintainer or the original bug submitter are allowed to close
+bugs. However, the person making the non-maintainer release must send
+a short message, including the patch for that NMU, to the relevant
+bugs explaining that the bugs have been fixed by the NMU. Using
<email/control@bugs.debian.org/, the party doing the NMU should also
set the severity of the bugs fixed in the NMU to `fixed'. This
ensures that everyone knows that the bug was fixed in an NMU; however
the bug is left open until the changes in the NMU are incorporated
"officially" into the package by the official package maintainer.
<p>
-The normal maintainer should do at least one of the following:
- <list compact>
- <item>
-apply the diff,
- <item>
-read the diff and decide on each part of it themselves, or
- <item>
-if the maintainer decides not to apply the patch but to release a new
-version, read the description of the changes to the next upstream
-version and ensure that they fix each problem that was fixed in the
-non-maintainer release.
- </list>
+The normal maintainer will either apply the patch or employ an
+alternate method of fixing the problem. Sometimes bugs are fixed
+independantly 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, read the description of the changes to
+the next upstream version and ensure that they fix each problem that
+was fixed in the non-maintainer release.
<p>
In addition, the normal maintainer should <em/always/ include an entry
in the changelog file documenting the non-maintainer upload.
-
- <sect>Maintainer changes
- <p>
-Periodically, a listing of packages in need of new maintainers will be
-sent to <email/debian-devel@lists.debian.org</email> list. This list
-is also available at in the Work-Needing and Prospective Packages
-document (WNPP), <url
-id="ftp://ftp.debian.org/debian/doc/package-developer/prospective-packages.html">
-and at <url id="http://www.debian.org/doc/prospective-packages.html">.
-If you wish to take over maintenance of any of the packages listed in
-the WNPP, or if you can no longer maintain a packages you have, or you
-simply want to know if any one is working on a new package, send a
-message to <email/wnpp@debian.org/.
-
- <p>
-If you take over an old package, you probably want to be listed as the
-package's official maintainer in the bug system. This will happen
-automatically once you upload a new version with an updated
-<tt/Maintainer:/ field. If you do not expect to upload a new version
-for a while, send an email to <email/override-change@debian.org/ so
-that bug reports will go to you.
+<sect id="porter-guidelines">Guidelines for Porters
- <chapt id="archive-manip">Moving, Removing, Renaming, and Orphaning Packages
+ <chapt id="archive-manip">Moving, Removing, Renaming, Adopting, and Orphaning Packages
<p>
Some archive manipulation operation are not automated in the Debian
upload process. This chapter gives guidelines in what to do in these
obsolete name.
+
<sect>Orphaning a package
<p>
If you can no longer maintain a package, then you should set the
maintainer.
+ <sect>Adopting a package
+ <p>
+Periodically, a listing of packages in need of new maintainers will be
+sent to <email/debian-devel@lists.debian.org</email> list. This list
+is also available at in the Work-Needing and Prospective Packages
+document (WNPP), <url
+id="ftp://ftp.debian.org/debian/doc/package-developer/prospective-packages.html">
+and at <url id="http://www.debian.org/doc/prospective-packages.html">.
+If you wish to take over maintenance of any of the packages listed in
+the WNPP, or if you can no longer maintain a packages you have, or you
+simply want to know if any one is working on a new package, send a
+message to <email/wnpp@debian.org/.
+
+ <p>
+If you take over an old package, you probably want to be listed as the
+package's official maintainer in the bug system. This will happen
+automatically once you upload a new version with an updated
+<tt/Maintainer:/ field. If you do not expect to upload a new version
+for a while, send an email to <email/override-change@debian.org/ so
+that bug reports will go to you.
+
+
+
+
<chapt id="bug-handling">Handling Bug Reports
<sect>Monitoring bugs
~ianmdlvl / developers-reference.git / blobdiff