<section id="nmu">
<title>Non-Maintainer Uploads (NMUs)</title>
<para>
-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.
-</para>
-<para>
-This section handles only source NMUs, i.e. NMUs which upload a new version of
-the package. For binary-only NMUs by porters or QA members, please see <xref
-linkend="binary-only-nmu"/> . If a buildd builds and uploads a package, that
-too is strictly speaking a binary NMU. See <xref linkend="wanna-build"/> for
-some more information.
-</para>
-<para>
-The main reason why NMUs are done is when a developer needs to fix another
-developer's package in order to address serious problems or crippling bugs or
-when the package maintainer is unable to release a fix in a timely fashion.
-</para>
-<para>
-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
-<emphasis>not</emphasis> be made in a non-maintainer upload.
-</para>
-<para>
-And please remember the Hippocratic Oath: Above all, do no harm. It is better
-to leave a package with an open grave bug than applying a non-functional patch,
-or one that hides the bug instead of resolving it.
+Every package has one or more maintainers. Normally, these are the people who
+work on and upload new versions of the package. In some situations, it is
+useful that other developers can upload a new version as well, for example if
+they want to fix a bug in a package they don't maintain, when the maintainer
+needs help to respond to issues. Such uploads are called
+<emphasis>Non-Maintainer Uploads (NMU)</emphasis>.
</para>
+
<section id="nmu-guidelines">
-<title>How to do a NMU</title>
-<para>
-NMUs which fix important, serious or higher severity bugs are encouraged and
-accepted. You should endeavor to reach the current maintainer of the package;
-they might be just about to upload a fix for the problem, or have a better
-solution.
-</para>
-<para>
-NMUs should be made to assist a package's maintainer in resolving bugs.
-Maintainers should be thankful for that help, and NMUers should respect the
-decisions of maintainers, and try to personally help the maintainer by their
-work.
-</para>
+<title>When and how to do an NMU</title>
+
<para>
-A NMU should follow all conventions, written down in this section. For an
-upload to <literal>testing</literal> or <literal>unstable</literal>, this
-order of steps is recommended:
+Before doing an NMU, consider the following questions:
</para>
<itemizedlist>
<listitem>
<para>
-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.
+Does your NMU really fix bugs? Fixing cosmetic issues or changing the
+packaging style in NMUs is discouraged.
</para>
</listitem>
<listitem>
<para>
-Wait a few days for the response from the maintainer. If you don't get any
-response, you may want to help them by sending the patch that fixes the bug.
-Don't forget to tag the bug with the patch keyword.
+Did you give enough time to the maintainer? When was the bug reported to the
+BTS? Being busy for a week or two isn't unusual. Is the bug so severe that it
+needs to be fixed right now, or can it wait a few more days?
</para>
</listitem>
<listitem>
<para>
-Wait a few more days. If you still haven't got an answer from the maintainer,
-send them a mail announcing your intent to NMU the package. Prepare an NMU as
-described in this section, and test it carefully on your machine (cf. <xref
-linkend="sanitycheck"/> ). Double check that your patch doesn't have any
-unexpected side effects. Make sure your patch is as small and as
-non-disruptive as it can be.
+How confident are you about your changes? Please remember the Hippocratic Oath:
+"Above all, do no harm." It is better to leave a package with an open grave bug
+than applying a non-functional patch, or one that hides the bug instead of
+resolving it. If you are not 100% sure of what you did, it might be a good idea
+to seek advice from others. Remember that if you break something in your NMU,
+many people will be very unhappy about it.
</para>
</listitem>
<listitem>
<para>
-Upload your package to incoming in <filename>DELAYED/7-day</filename> (cf.
-<xref linkend="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.
+Have you clearly expressed your intention to NMU, at least in the BTS?
+It is also a good idea to try to contact the
+maintainer by other means (private email, IRC).
</para>
</listitem>
<listitem>
<para>
-Follow what happens, you're responsible for any bug that you introduced with
-your NMU. You should probably use <xref linkend="pkg-tracking-system"/> (PTS)
-to stay informed of the state of the package after your NMU.
+If the maintainer is usually active and responsive, have you tried to contact
+him? In general it should be considered preferable that a maintainer takes care
+of an issue himself and that he is given the chance to review and correct your
+patch, because he can be expected to be more aware of potential issues which an
+NMUer might miss. It is often a better use of everyone's time if the maintainer
+is given an opportunity to upload a fix on their own.
</para>
</listitem>
</itemizedlist>
<para>
-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. Please see <xref
-linkend="qa-bsp"/> for details.
+When doing an NMU, you must first make sure that your intention to NMU is
+clear. Then, you must send a patch with the differences between the
+current package and your proposed NMU to the BTS. The
+<literal>nmudiff</literal> script in the <literal>devscripts</literal> package
+might be helpful.
</para>
<para>
-For the <literal>testing</literal> distribution, the rules may be changed by
-the release managers. Please take additional care, and acknowledge that the
-usual way for a package to enter <literal>testing</literal> is through
-<literal>unstable</literal>.
+While preparing the patch, you should better be aware of any package-specific
+practices that the maintainer might be using. Taking them into account reduces
+the burden of getting your changes integrated back in the normal package
+workflow and thus increases the possibilities that that will happen. A good
+place where to look for for possible package-specific practices is
+<ulink url="&url-debian-policy;ch-source.html#s-readmesource"><literal>debian/README.source</literal></ulink>.
</para>
<para>
-For the stable distribution, please take extra care. Of course, the release
-managers may also change the rules here. Please verify before you upload that
-all your changes are OK for inclusion into the next stable release by the
-release manager.
+Unless you have an excellent reason not to do so, you must then give some time
+to the maintainer to react (for example, by uploading to the
+<literal>DELAYED</literal> queue). Here are some recommended values to use for delays:
</para>
+<itemizedlist>
+<listitem>
<para>
-When a security bug is detected, the security team may do an NMU, using their
-own rules. Please refer to <xref linkend="bug-security"/> for more
-information.
+Upload fixing only release-critical bugs older than 7 days: 2 days
</para>
+</listitem>
+<listitem>
<para>
-For the differences for Porters NMUs, please see <xref
-linkend="source-nmu-when-porter"/> .
+Upload fixing only release-critical and important bugs: 5 days
</para>
+</listitem>
+<listitem>
<para>
-Of course, it is always possible to agree on special rules with a maintainer
-(like the maintainer asking please upload this fix directly for me, and no diff
-required).
+Other NMUs: 10 days
</para>
-</section>
+</listitem>
+</itemizedlist>
-<section id="nmu-version">
-<title>NMU version numbering</title>
<para>
-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.
+Those delays are only examples. In some cases, such as uploads fixing security
+issues, or fixes for trivial bugs that blocking a transition, it is desirable
+that the fixed package reaches <literal>unstable</literal> sooner.
</para>
+
<para>
-If you are doing a non-maintainer upload (NMU), you should add a new minor
-version number to the <replaceable>debian-revision</replaceable> 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
-<filename>foo_1.1-3.dsc</filename>. 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
-<filename>foo_1.1-3.1.dsc</filename>.
-</para>
-<para>
-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.
+Sometimes, release managers decide to allow NMUs with shorter delays for a
+subset of bugs (e.g release-critical bugs older than 7 days). Also, some
+maintainers list themselves in the <ulink url="&url-low-threshold-nmu;">Low
+Threshold NMU list</ulink>, and accept that NMUs are uploaded without delay. But
+even in those cases, it's still a good idea to give the maintainer a few days
+to react before you upload, especially if the patch wasn't available in the BTS
+before, or if you know that the maintainer is generally active.
</para>
+
<para>
-If there is no <replaceable>debian-revision</replaceable> component in the
-version number then one should be created, starting at `0.1' (but in case of a
-debian native package still upload it as native package). 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 <replaceable>debian-revision</replaceable> value `0.1'. The usual
-maintainer of a package should start their
-<replaceable>debian-revision</replaceable> numbering at `1'.
+After you upload an NMU, you are responsible for the possible problems that you
+might have introduced. You must keep an eye on the package (subscribing to the
+package on the PTS is a good way to achieve this).
</para>
+
<para>
-If you upload a package to <literal>testing</literal> or <literal>stable
-</literal>, sometimes, you need to fork the version number tree. For this,
-version numbers like 1.1-3sarge0.1 could be used.
+This is not a license to perform NMUs thoughtlessly. If you NMU when it is
+clear that the maintainers are active and would have acknowledged a patch in a
+timely manner, or if you ignore the recommendations of this document, your
+upload might be a cause of conflict with the maintainer.
+You should always be prepared to
+defend the wisdom of any NMU you perform on its own merits.
</para>
</section>
<section id="nmu-changelog">
-<title>Source NMUs must have a new changelog entry</title>
+<title>NMUs and debian/changelog</title>
<para>
-Anyone who is 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 email address of the person
-who uploaded it in the log entry and the NMU version number in it.
-</para>
-<para>
-By convention, source NMU changelog entries start with the line
+Just like any other (source) upload, NMUs must add an entry to
+<literal>debian/changelog</literal>, telling what has changed with this
+upload. The first line of this entry must explicitely mention that this upload is an NMU, e.g.:
</para>
<screen>
- * Non-maintainer upload
+ * Non-maintainer upload.
</screen>
-</section>
-<section id="nmu-patch">
-<title>Source NMUs and the Bug Tracking System</title>
<para>
-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 (<literal>diff -u</literal>) detailing their changes to
-the Bug Tracking System.
+The version must be the version of the last maintainer upload, plus
+<literal>+nmu<replaceable>X</replaceable></literal>, where
+<replaceable>X</replaceable> is a counter starting at <literal>1</literal>. If
+the last upload was also an NMU, the counter should be increased. For example,
+if the current version is <literal>1.5-1</literal>, then an NMU would get
+version <literal>1.5-1+nmu1</literal>. If the current version is
+<literal>1.5+nmu3</literal> (a native package which has already been NMUed), the
+NMU would get version <literal>1.5+nmu4</literal>. If a new upstream version
+is packaged in the NMU, the debian revision is set to <literal>0</literal>, for
+example <literal>1.6-0+nmu1</literal>.
+</para>
+
+<para>
+A special versioning scheme is needed to avoid disrupting the maintainer's
+work, since using an integer for the Debian revision will potentially
+conflict with a maintainer upload already in preparation at the time of an
+NMU, or even one sitting in the ftp NEW queue.
+It also has the
+benefit of making it visually clear that a package in the archive was not made
+by the official maintainer.
</para>
+
<para>
-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
-<xref linkend="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.
+If you upload a package to testing or stable, you sometimes need to "fork" the
+version number tree. This is the case for security uploads, for example. For
+this, a version of the form
+<literal>+deb<replaceable>XY</replaceable>u<replaceable>Z</replaceable></literal>
+should be used, where <replaceable>X</replaceable> and
+<replaceable>Y</replaceable> are the major and minor release numbers, and
+<replaceable>Z</replaceable> is a counter starting at <literal>1</literal>.
+When the release number is not yet known (often the case for
+<literal>testing</literal>, at the beginning of release cycles), the lowest
+release number higher than the last stable release number must be used. For
+example, while Etch (Debian 4.0) is stable, a security NMU to stable for a
+package at version <literal>1.5-3</literal> would have version
+<literal>1.5-3+deb40u1</literal>, whereas a security NMU to Lenny would get
+version <literal>1.5-3+deb50u1</literal>. After the release of Lenny, security
+uploads to the <literal>testing</literal> distribution will be versioned
+<literal>+deb51uZ</literal>, until it is known whether that release will be
+Debian 5.1 or Debian 6.0 (if that becomes the case, uploads will be versioned
+as <literal>+deb60uZ</literal>.
</para>
+</section>
+
+<section id="nmu-delayed">
+<title>Using the <literal>DELAYED/</literal> queue</title>
+
<para>
-Bugs fixed by source NMUs used to be tagged fixed instead of closed, but since
-version tracking is in place, such bugs are now also closed with the NMU
-version.
+Having to wait for a response after you request permission to NMU is
+inefficient, because it costs the NMUer a context switch to come back to the
+issue.
+The <literal>DELAYED</literal> queue (see <xref linkend="delayed-incoming"/>)
+allows the developer doing the NMU to perform all the necessary tasks at the
+same time. For instance, instead of telling the maintainer that you will
+upload the updated
+package in 7 days, you should upload the package to
+<literal>DELAYED/7</literal> and tell the maintainer that he has 7 days to
+react. During this time, the maintainer can ask you to delay the upload some
+more, or cancel your upload.
</para>
+
<para>
-Also, after doing an NMU, you have to send the information to the existing bugs
-that are fixed by your NMU, including the unified diff. Historically, it was
-custom to open a new bug and include a patch showing all the changes you have
-made. 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.
+The <literal>DELAYED</literal> queue should not be used to put additional
+pressure on the maintainer. In particular, it's important that you are
+available to cancel or delay the upload before the delay expires since the
+maintainer cannot cancel the upload himself.
</para>
+
<para>
-In addition, the normal maintainer should <emphasis>always</emphasis> retain
-the entry in the changelog file documenting the non-maintainer upload -- and of
-course, also keep the changes. If you revert some of the changes, please
-reopen the relevant bug reports.
+If you make an NMU to <literal>DELAYED</literal> and the maintainer updates
+his package before the delay expires, your upload will be rejected because a
+newer version is already available in the archive.
+Ideally, the maintainer will take care to include your proposed changes (or
+at least a solution for the problems they address) in that upload.
</para>
+
</section>
-<section id="nmu-build">
-<title>Building source NMUs</title>
+<section id="nmu-maintainer">
+<title>NMUs from the maintainer's point of view</title>
+
<para>
-Source NMU packages are built normally. Pick a distribution using the same
-rules as found in <xref linkend="distribution"/> , follow the other
-instructions in <xref linkend="upload"/> .
+When someone NMUs your package, this means they want to help you to keep it in
+good shape. This gives users fixed packages faster. You
+can consider asking the NMUer to become a co-maintainer of the package.
+Receiving an NMU on a package is not a bad
+thing; it just means that the package is interesting enough for other people to
+work on it.
</para>
+
<para>
-Make sure you do <emphasis>not</emphasis> change the value of the maintainer in
-the <filename>debian/control</filename> file. Your name as given in the NMU
-entry of the <filename>debian/changelog</filename> file will be used for
-signing the changes file.
+To acknowledge an NMU, include its changes and changelog entry in your next
+maintainer upload. If you do not acknowledge the NMU by including the
+NMU changelog entry in your changelog, the bugs will remain closed in the
+BTS but will be listed as affecting your maintainer version of the package.
</para>
+
</section>
-<section id="ack-nmu">
-<title>Acknowledging an NMU</title>
+<section id="nmu-binnmu">
+<title>Source NMUs vs Binary-only NMUs (binNMUs)</title>
+
<para>
-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. The easiest way is to use the
-<literal>-v</literal> option of <command>dpkg-buildpackage</command>, as this
-allows you to include just all changes since your last maintainer upload.
-Alternatively, you can close them manually by sending the required mails to the
-BTS or by adding the required <literal>closes: #nnnn</literal> in the changelog
-entry of your next upload.
+The full name of an NMU is <emphasis>source NMU</emphasis>. There is also
+another type, namely the <emphasis>binary-only NMU</emphasis>, or
+<emphasis>binNMU</emphasis>. A binNMU is also a package upload by someone
+other than the package's maintainer. However, it is a binary-only upload.
</para>
+
<para>
-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 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 in helping
-you on a more frequent basis as co-maintainer or backup maintainer (see <xref
-linkend="collaborative-maint"/> ).
+When a library (or other dependency) is updated, the packages using it may need
+to be rebuilt. Since no changes to the source are needed, the same source
+package is used.
</para>
-</section>
-<section id="nmu-vs-qa">
-<title>NMU vs QA uploads</title>
<para>
-Unless you know the maintainer is still active, it is wise to check the package
-to see if it has been orphaned. The current list of orphaned packages which
-haven't had their maintainer set correctly is available at <ulink
-url="&url-debian-qa-orphaned;"></ulink>. If you perform an NMU on an
-improperly orphaned package, please set the maintainer to <literal>Debian QA Group
-<packages@qa.debian.org></literal>.
+BinNMUs are usually triggered on the buildds by wanna-build.
+An entry is added to debian/changelog,
+explaining why the upload was needed and increasing the version number as
+described in <xref linkend="binary-only-nmu"/>.
+This entry should not be included in the next upload.
</para>
-</section>
-<section id="nmu-who">
-<title>Who can do an NMU</title>
<para>
-Only official, registered Debian Developers can do binary or source NMUs. A
-Debian Developer 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.
+Buildds upload packages for their architecture to the archive as binary-only
+uploads. Strictly speaking, these are binNMUs. However, they are not normally
+called NMU, and they don't add an entry to debian/changelog.
</para>
+
</section>
-<section id="nmu-terms">
-<title>Terminology</title>
+<section id="nmu-qa-upload">
+<title>NMUs vs QA uploads</title>
+
<para>
-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
-<literal>non-maintainer</literal> upload.
+NMUs are uploads of packages by somebody else than their assigned maintainer.
+There is
+another type of upload where the uploaded package is not yours: QA uploads. QA
+uploads are uploads of orphaned packages.
</para>
+
<para>
-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
-<filename>debian/changelog</filename>). 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.
+QA uploads are very much like normal maintainer uploads: they may fix anything,
+even minor issues; the version numbering is normal, and there is no need to use
+a delayed upload. The difference is that you are not listed as the Maintainer
+or Uploader for the package. Also, the changelog entry of a QA upload has a
+special first line:
</para>
+
+<screen>
+ * QA upload.
+</screen>
+
<para>
-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.
+If you want to do an NMU, and it seems that the maintainer is not active, it is
+wise to check if the package is orphaned
+(this information is displayed on the package's Package Tracking System page).
+When doing the first QA upload to an
+orphaned package, the maintainer should be set to <literal>Debian QA Group
+<packages@qa.debian.org></literal>. Orphaned packages which did
+not yet have a QA upload still have their old maintainer set. There is a list
+of them at <ulink url="&url-orphaned-not-qa;"/>.
</para>
+
<para>
-Both classes of NMUs, source and binary-only, can be lumped under 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: always use
-``binary NMU'' or ``binNMU'' for binary-only NMUs.
+Instead of doing a QA upload, you can also consider adopting the package by
+making yourself the maintainer. You don't need permission from anybody to
+adopt an orphaned package, you can just set yourself as maintainer and upload
+the new version (see <xref linkend="adopting"/>).
</para>
+
</section>
</section>
<listitem>
<para>
It must be available on all architectures on which it has previously been built
-in <literal>unstable</literal>. <xref linkend="dak ls"/> may be of interest
+in <literal>unstable</literal>. <xref linkend="dak-ls"/> may be of interest
to check that information;
</para>
</listitem>
~ianmdlvl / developers-reference.git / blobdiff