+
+ <sect1 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'. Note that if you do
+this, you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the
+<tt>-sa</tt> 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 yet clever enough 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 version
+numbers if and only if they actually have to modify the source package
+in some way, i.e., if they are doing a source NMU and not a binary
+NMU.
+
+
+ <sect1 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>
+ <p>
+By convention, source NMU changelog entries start with the line
+<example>
+ * Non-maintainer upload
+</example></p></sect1>
+
+
+ <sect1 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? In this case, the
+process is different for porters than it is for non-porters, as
+mentioned above. If you are not a porter and 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</package>), there must still be a changelog entry;
+therefore, there will be a patch. If you are a porter, you are
+probably just doing a binary-only NMU. (Note: this leaves out in the cold
+porters who have to do recompiles — chalk it up as a weakness in how
+we maintain our archive.)
+ <p>
+If the source NMU (non-maintainer upload) fixes some existing bugs,
+the bugs in the Bug Tracking System which are fixed need to be
+<em>notified</em> but not actually <em>closed</em> 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 to
+the relevant bugs explaining that the bugs have been fixed by the NMU.
+Using <email>control@bugs.debian.org</email>, 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. Also, open a bug with the patches needed to fix the
+problem, or make sure that one of the other (already open) bugs has
+the patches.
+ <p>
+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.
+
+
+ <sect1 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, including
+the need to announce the NMU to the proper lists.
+ <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.
+
+
+
+
+ <chapt 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 is amounts to
+&number-of-arches; more builds.
+
+
+ <sect id="kind-to-porters">Being Kind to Porters
+ <p>
+Porters have a difficult and unique task, since they are required to
+deal with a large volume of packages. Ideally, every source package
+should build right out of the box. Unfortunately, this is often not
+the case. This section contains a checklist of ``gotchas'' often
+committed by Debian maintainers — common problems which often stymie
+porters, and make their jobs unnecessarily difficult.
+ <p>
+The first and most important watchword is to respond quickly to bug or
+issues raised by porters. Please treat porters with courtesy, as if
+they were in fact co-maintainers of your package (which in a way, they
+are). Please be tolerant of succinct or even unclear bug reports,
+doing your best to hunt down whatever the problem is.
+ <p>
+By far, most of the problems encountered by porters are caused by
+<em>packaging bugs</em> in the source packages. Here is a checklist
+of things you should check or be aware of.
+
+<enumlist>
+ <item>
+Make sure that your <tt>Build-Depends</tt> and
+<tt>Build-Depends-Indep</tt> settings in <file>debian/control</file>
+are set properly. The best way to validate this is to use the
+<package>debootstrap</package> package to create an unstable chroot
+environment. Within that chrooted environment, install the
+<package>build-essential</package> package and any package
+dependancies mention in <tt>Build-Depends</tt> and/or
+<tt>Build-Depends-Indep</tt>. Finally, try building your package
+within that chrooted environment.
+ <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
+<tt>dpkg-buildpackage</tt>.
+ <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 Packaging 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>
+
+
+ <sect 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-only 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, you are actually doing a source NMU, so consult <ref
+id="nmu-guidelines"> instead.
+ <p>
+In a binary-only NMU, 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 <file>debian/changelog</file>.
+ <p>
+The way to invoke <prgn>dpkg-buildpackage</prgn> is as
+<tt>dpkg-buildpackage -B -e<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-dependant portions of the
+package, using the `binary-arch' target in <file>debian/rules</file>.
+
+ <sect1 id="recompile-nmu-versioning">
+ <heading>Recompilation Binary-Only NMU Versioning</heading>
+ <p>
+Sometimes you need to recompile a package against other packages which
+have been updated, such as libraries. You do have to bump the version
+number in this case, so that the version comparison system can
+function properly. Even so, these are considered 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''.
+
+
+ <sect1 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.
+ <p>
+Again, the situation varies depending on the distribution they are
+uploading to. 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 &mdash 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.
+
+
+ <sect>Tools for Porters