Whole document tree

Debian Developer's Reference
Chapter 7 - Non-Maintainer Uploads (NMUs)

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.

Debian porters, who compile packages for different architectures, do NMUs as part of their normal porting activity (see Porting and Being Ported, Chapter 8). 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.

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.

7.1 Terminology

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 non-maintainer upload.

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 debian/changelog). 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 (or, more rarely, new upstream source as well).

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.

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.

7.2 Who can do an NMU

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.

7.3 When to do a source NMU

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 When to do a source NMU if you are a porter, Section 8.2.2).

When a security bug is detected, a fixed package should be uploaded as soon as possible. In this case, the Debian security officers 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, a security officer may upload a fixed package (i.e., do a source NMU).

During the release cycle (see Stable, testing, and unstable, Section 5.6.1), 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 How to do a source NMU, Section 7.4 need to be followed.

Bug fixes to unstable by non-maintainers are also acceptable, but only 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:

• Make sure that the package bug is in the Debian Bug Tracking System (BTS). If not, submit a bug.

• Email the maintainer, and offer to help fix the package bug. Give it a few days.

• Go ahead and fix the bug, submitting a patch to the right bug in the BTS. Build the package and test it as discussed in Checking the package prior to upload, Section 6.3. Use it locally.

• Wait a couple of weeks for a response.

• Email the maintainer, asking if it is OK to do an NMU.

• 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.

• Wait another week for a response.

• Go ahead and do the source NMU, as described in How to do a source NMU, Section 7.4.

7.4 How to do a source NMU

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 Guidelines for Porter Uploads, Section 8.2.

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 not be made in a non-maintainer upload.

7.4.1 Source NMU version numbering

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.

If you are doing a non-maintainer upload (NMU), you should add a new minor version number to the 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 foo_1.1-3.dsc. 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 foo_1.1-3.1.dsc.

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.

If there is no 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 debian-revision value `0.1'. The usual maintainer of a package should start their debian-revision numbering at `1'. Note that if you do this, you'll have to invoke dpkg-buildpackage with the -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 yet clever enough to know about `0.1').

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.

7.4.2 Source NMUs must have a new changelog entry

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.

By convention, source NMU changelog entries start with the line

       * Non-maintainer upload

7.4.3 Source NMUs and the Bug Tracking System

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 (diff -u) detailing their changes to the Bug Tracking System.

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 debhelper), 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.)

If the source NMU (non-maintainer upload) fixes some existing bugs, these bugs should be tagged fixed 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 Closes: bug#nnnnn syntax (see When bugs are closed by new uploads, Section 10.4 for more information describing how to close bugs via the changelog). Tagging the bugs fixed 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, after doing an NMU, you have 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.

In addition, the normal maintainer should always retain the entry in the changelog file documenting the non-maintainer upload.

7.4.4 Building source NMUs

Source NMU packages are built normally. Pick a distribution using the same rules as found in Picking a distribution, Section 6.4.2. Just as described in Uploading a package, Section 6.5, a normal changes file, etc., will be built. In fact, all the prescriptions from Package uploads, Chapter 6 apply, including the need to announce the NMU to the proper lists.

Make sure you do not change the value of the maintainer in the debian/control file. Your name as given in the NMU entry of the debian/changelog file will be used for signing the changes file.

Debian Developer's Reference