You can also obtain it by writing to the Free Software Foundation,
Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
- <toc sect>
+ <toc detail="sect2">
<chapt id="scope">Scope of This Document
<p>
<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 interim releases of other
-maintainer's packages (<ref id="nmu">); how to move, remove, or orphan
+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">).
<p>
</example>
<p>
As you can see, the top-level directory of the distribution contains
-three directories, namely <em>main</>, <em>contrib</>, and
-<em>non-free</>. These directories are called <em>sections</>.
+three directories, namely <em/main/, <em/contrib/, and
+<em/non-free/. These directories are called <em/sections/.
<p>
In each section, there is a directory with the source packages
(source), a directory for each supported architecture
<sect>Sections
<p>
The <em>main</em> section is what makes up the <em>official Debian
-GNU/Linux distribution</>. The <em/main/ section is official because
+GNU/Linux distribution</em>. The <em/main/ section is official because
it fully complies with all our guidelines. The other two sections do
not, to different degrees; as such, they are not officially part of
Debian.
<p>
On the other hand, if we called the distribution directories
<em>Debian-x.y</em> from the beginning, people would think that Debian
-release <em>x.y</> is available. (This happened in the past, where a
+release <em>x.y</em> is available. (This happened in the past, where a
CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development
version. That's the reason why the first official Debian release was
1.1, and not 1.0.)
<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. This is
+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, 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.
+binary NMUs as part of their normal porting activity. Less often,
+Debian developers do NMUs for other developers' packages 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
-get in contact with the package maintainer to make sure a fixed
-package is uploaded within a reasonable time (less than 48 hours). If
-the package maintainer cannot provide a fixed package fast enough or
-if he/she cannot be reached in time, the Security Manager may upload a
-fixed package.
+how NMUs should be done. It also contains information for when a port
+is just a port, or when it is also an NMU, and how these should be
+done.
+
+ <sect id="nmu-terms">Terminology
+ <p>
+There are two new terms used throughout this section: ``NMU'' and
+``port''. These terms are used with specific technical meaning
+throughout this document; common parlance may vary.
+ <p>
+Both ports and NMUs are similar, since they involve an upload of a
+package by a developer who is not the regular maintainer. In common
+parlance, ports are also NMUs since any upload of a package by a
+developer who is not the official maintainer is an NMU (i.e.,
+non-maintainer upload). However, in this chapter, I distinguish
+between ports and NMUs artificially in order to keep my meaning clear.
+ <p>
+An NMU is a upload of a package by a developer who is not the official
+maintainer for the purposes of fixing a bug in the package. In my
+usage, NMUs always involves changes to the source (even if it is just
+a change to <tt>debian/changelog</tt>). This can be either a change
+to the upstream source, or a change to the Debian bits of the source.
+ <p>
+A port is a recompilation and upload of a binary packages for a
+specific architecture. There are ports where no source changes are
+needed and ports where the source has to be changed. In this chapter,
+``port'' means a non-maintainer uploaded binary version of a packge
+for anther version, with no source changes needed. Of course, there
+are many cases where porters must fix problems in the source in order
+to get them to compile for their target architecture; however, this
+case is considered to be an NMU rather than a port.
+
+
+ <sect id="nmu-who">Who can do a port or an NMU
+ <p>
+Only official Debian maintainers can do ports or NMUs. This is
+because we need to ensure that trojans or other problems are not
+inserted into the archive. 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 a port or an NMU
+ <p>
+Porters usually use systems such as <package/quinn-diff/ (<ref
+id="quinn-diff">) to tell them what packages need to be compiled for a
+given architecture. See <ref id="porter-guidelines"> for more
+information on how to do this type of upload. Porters are always
+uploading to either frozen or unstable.
+ <p>
+NMU guidelines for when to do an NMU depends on the target
+distribution, i.e., stable, unstable, or frozen.
+ <p>
+Only critical changes or security bugfixes make it into stable. When
+a security bug is detected a fixed package should be uploaded as soon
+as possible. In this case, the Debian Security Managers should get in
+contact with the package maintainer to make sure a fixed package is
+uploaded within a reasonable time (less than 48 hours). If the package
+maintainer cannot provide a fixed package fast enough or if he/she
+cannot be reached in time, the Security Manager may upload a fixed
+package.
<p>
During the release freeze (see <ref id="upload-frozen">), NMUs which
fix important or higher severity bugs are encouraged and accepted.
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:
+as a last resort or with permission. Try the following steps first,
+and if they don't work, it is probably 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>
+ <item>
+Make sure that the package bug is in the Debian Bug Tracking System
+(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>
+ <item>
+Go ahead and fix the bug, submitting a patch to the right bug in the
+BTS.
+ <item>
Wait a couple of weeks for a response.
- <item>
+ <item>
Email the maintainer, asking if it is ok to do an NMU.
- <item>
+ <item>
Wait a couple of weeks for a response.
- <item>
+ <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>
+ </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>
+ <sect1>When to do an NMU if you are a porter
+ <p>
+Porters doing an NMU as well -- i.e., if the source needs changing --
+generally follow the above guidelines, just like normal NMUs.
+However, it is expected that the wait cycle for a porter NMU is
+smaller than normal, since porters have to cope 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.
+uploading to. Crucial fixes (i.e., changes need to get a source
+package to compile for a released-targetted architecture) 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.
+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 ten
+days for porters working on the unstable distribution.
+ <p>
+Secondly, porters doing NMUs should make sure that the bug they 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 by release time.
<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,
+version of the compile environment, kernel, or libc. Sometimes such
+kluges 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.
+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 waiting periods have no official
+blessing from Debian.
-<sect id="nmu-guidelines">How to do an NMU
-
+ <sect id="nmu-guidelines">How to do an NMU
+ <p>
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.
+Remember that we are making a distinction between a <em/port/ and an
+<em/NMU/ (see <ref id="nmu-terms">).
<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">.
+role of being both NMU bug-fixers and porters. If a porter has to
+change the Debian source archive, automatically their upload is an NMU
+and is subject to its rules. If a porter is simply uploading a port,
+the rules are different; see <ref id="porter-guidelines">.
-<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>
+
+ <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
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/
-value `0.1'. The usual maintainer of a package should start their
-<var/debian-revision/ numbering at `1'. Note that if you do this,
-you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the <tt/-sa/
-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>
+ <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/ 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/ value `0.1'. The
+usual maintainer of a package should start their <var/debian-revision/
+numbering at `1'. Note that if you do this, you'll have to invoke
+<prgn>dpkg-buildpackage</prgn> with the <tt/-sa/ switch to force the
+build system to pick up the new source package (normally it only looks
+for Debian revisions of '0' or '1'; it's not clever enough yet to know
+about `0.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>
+
+ <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
+
+ <sect1 id="nmu-patch">NMUs must send patches, if any, to the BTS
+ <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/) 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
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 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
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 id="porter-guidelines">Guidelines for Porters
+
+ <sect1 id="nmu-build">Building the NMU
+ <p>
+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 presecriptions from <ref id="upload"> apply, including the
+need to announce the NMU to the proper lists.
+ <p>
+Make sure you do <em/not/ change the value of the maintainer in the
+<tt>debian/control</tt> file. Your name from the NMU entry of the
+<tt>debian/changelog</tt> file will be used for signing the changes
+file.
+
+
+ <sect id="porter-guidelines">Guidelines for Porters
+ <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 NMU 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, read
+<ref id="nmu-guidelines"> instead.
+ <p>
+Since no real changes are being made to the source, you do not need to
+touch any of the files in the source package. This includes
+<tt>debian/changelog</tt>.
+ <p>
+The way to invoke <prgn/dpkg-buildpackage/ is as <tt>dpkg-buildpackage
+-B -m<var/porter-email/</tt>. Of course, set <var/porter-email/ to
+your email address. This will do a binary-only build of only the
+architecture-dependant portions of the package. In case of a somewhat
+broken <tt>debian/rules</tt> file, resorting to <tt>dpkg-buildpackage
+-b -m<var/porter-email/</tt> is also acceptable. But remember to file
+a bug against the package that the <tt/binary-arch/ rule is broken!
- <chapt id="archive-manip">Moving, Removing, Renaming, Adopting, and Orphaning Packages
+ <chapt id="archive-manip"><heading>Moving, Removing, Renaming,
+ Adopting, and Orphaning Packages</heading>
<p>
Some archive manipulation operation are not automated in the Debian
-upload process. This chapter gives guidelines in what to do in these
+upload process. These procedures should be manually followed by
+maintainers. This chapter gives guidelines in what to do in these
cases.
<sect>Moving packages
package should be removed from.
<p>
If in doubt concerning whether a package is disposable, email
-<email/debian-devel@lists.debian.org/ asking for opinions.
-
+<email/debian-devel@lists.debian.org/ asking for opinions. Also of
+interest is the <prgn/apt-cache/ program from the <package/apt/
+package. When invoked as <tt>apt-cache showpkg
+/var/cache/apt/pkgcache.bin <var/package/</tt>, the program will show
+details for <var/package/, including reverse depends.
<sect>Replacing or renaming packages
<p>
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.
+<tt/Maintainer:/ field, although it can take a couple of weeks. 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
+right away.
<sect>Reporting lots of bugs at once
<p>
+Reporting a great number of bugs for the same problem on a great
+number of different packages -- i.e., more than 10 -- is a deprecated
+practice. Take all possible steps to avoid submitting bulk bugs at
+all. For instance, if checking for the problem can be automated, add
+a new check to <package/lintian/ so that an error or warning is
+emitted.
+ <p>
If you report more then 10 bugs on the same topic at once, it is
recommended that you send a message to
<email/debian-devel@lists.debian.org/ describing your intention before
-submitting the report. This will allow other developers to verify
-that the bug is a real problem. In addition, it will help prevent
-a situation in which several maintainers start filing the same bug
+submitting the report. This will allow other developers to verify that
+the bug is a real problem. In addition, it will help prevent a
+situation in which several maintainers start filing the same bug
report simultaneously.
<p>
Note that when sending lots of bugs on the same subject, you should
endorse any particular tool to the exclusion of a competing tool.
<p>
Most of the descriptions of these packages come from the actual
-package descriptions themselves.
+package descriptions themselves. Further information can be found in
+the package documentation itself.
<sect id="dpkg-dev">
<heading><package/dpkg-dev/
packages. These utilities contain the fundamental, low-level
functionality required to create and manipulated packages; as such,
they are required for any Debian maintainer.
+ <p>
+This package is maintained by Ian Jackson and the
+<email/debian-dpkg@lists.debian.org/ team.
<sect id="lintian">
<heading><package/lintian/
Debian policy as well as some checks for common errors. The use of
<package/lintian/ has already been discussed in <ref
id="upload-checking"> and <ref id="lintian-reports">.
+ <p>
+This package is maintained by Richard Braakman.
<sect id="debhelper">
<heading><package/debhelper/
several small, granular commands which act in a consistent manner. As
such, it allows a greater granularity of control than
<package/debmake/.
+ <p>
+This package is maintained by Joey Hess.
<sect id="debmake">
<heading><package/debmake/
source package; and <prgn>debstd</prgn>, which incorporates in one big
shot the same sort of automated functions that one finds in
<package/debhelper/.
+ <p>
+This package is maintained by Santiago Vila.
<sect id="cvs-buildpackage">
<heading><package/cvs-buildpackage/
of a package for <em/stable/, <em/unstable/, and possibly
<em/experimental/ distributions, along with the other benefits of a
version control system.
+ <p>
+This package is maintained by Manoj Srivastava.
<sect id="dupload">
<heading><package/dupload/
Debian packages to the Debian archive, to log the upload, and to send
mail about the upload of a package. You can configure it for new
upload locations or methods.
-
+ <p>
+This package is maintained by Heiko Schlittermann.
+
+ <sect id="quinn-diff">
+ <heading><package/quinn-diff/
+ <p>
+<!-- TODO: fact check -->
+<package/quinn-diff/ is used, by porters, primarily, to locate the
+differences from one architecture to another. For instance, it could
+tell you which packages need to be ported for architecture <var/Y/,
+based on architecture <var/X/.
+ <p>
+This package is maintained by James Troup.
+
+ <sect id="buildd">
+ <heading><package/buildd/
+ <p>
+<!-- TODO: fact check --> <package/buildd/ is not yet available!
+However, it collects a number of as yet unpackaged components which
+are currently in production (such as <prgn/debbuild/ and
+<prgn/wanna-build/.
+ <p>
+The <package/buildd/ system is used as a distributed, client-server
+build distribution system. It is usually used in conjunction with
+<em/auto-builders/, 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 autobuilt) and
+work on it.
+ <p>
+We are very excited about this system, since it potentially has so
+many uses. Independant 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 gcc
+bounds checking). It will also enable Debian to recompile entire
+distributions quickly.
</book>
</debiandoc>
~ianmdlvl / developers-reference.git / blobdiff