Hi,
This is the second call for comments (long overdue) on DEP1. (DEPs are
described in DEP0[0]). This document aims at clarifying the policies
and workflows used for NMUs inside Debian. Its main goal is to provide a
patch to section 5.11 of the Debian Developer's Reference, adressing the
current issues regarding NMUs.
Discussion already happened last month on debian-project@[1] and
debian-devel@[2]. You might want to have a look at these threads first.
The DEP can be found on http://wiki.debian.org/NmuDep (and also at the
end of this mail, so you can read it offline). When commenting on this
DEP, please create sub-threads on debian-project@ (changing the Subject)
for each point you raise, and avoid discussing several points in the
same mail.
[0] http://dep.alioth.debian.org/deps/dep0/
[1] http://lists.debian.org/debian-project/2008/04/msg00115.html
[2] http://lists.debian.org/debian-devel/2008/04/msg00745.html
Lucas Nussbaum and Bas Wijnen
------ DEP1 -------
=== Introduction and Motivation
In Debian, each package is "owned" by its maintainer, or by a small
group of maintainers, in the case of team maintenance. Modifying the
package requires going through those developers, which sometimes add a
long, unnecessary delay, especially in the case of inactive or busy
maintainers.
Non-maintainer uploads (NMUs) alleviate this problem, by allowing any
developer to upload a new version of another maintainer's package.
However, the current rules for NMUs are not very clear, so:
1. many developers prefer not to do NMUs.
2. different developers understand the rules differently, leading
to different opinions on what's allowed or not.
3. NMUs are often received with angry comments from maintainers.
This Debian Enhancement Proposal has two goals:
1. improve section 5.11 of the Developer's Reference, to clarify
it and address the current issues about NMUs. In particular:
1. We explicitely allow fixing bugs of severity lower than
important in NMUs
2. We encourage the use of the DELAYED queue
3. We try to encourage a responsible approach for NMUs,
instead of an approach based on strict rules
2. improve related tools, like the nmudiff script in the
devscripts package.
=== Proposed section 5.11: Non-Maintainer Uploads (NMUs)
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. Such uploads are called Non-Maintainer Uploads (NMU).
NMUs can happen for various reasons, the most usual one being to fix
bugs. There are some rules to follow when doing an NMU. These are
explained below. An NMU is allowed for any reason, as long as those
rules are followed.
5.11.1 When and how to do an NMU
There are no strict rules for NMUs, because there are many different
situations. However, before doing an NMU, consider the following
questions:
* Do you really fix bugs in your NMU? Fixing cosmetic issues, or
changing the packaging style in NMUs is discouraged, unless it
is required to fix bugs.
* Did you give enough time to the maintainer? 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?
* 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.
In most cases, the above points should not make you reconsider doing an
NMU. Fixing bugs is what really matters.
When doing an NMU, you must always send a patch with the differences
between the current package and your NMU to the BTS. If the bug you are
fixing isn't reported yet, you must do that as well.
While there are no general rules, it's recommended to upload to the
DELAYED queue with a delay of at least a few days. Here are some
examples that you could use as default values:
* Upload fixing only release-critical bugs older than 7 days: 2 days
* Upload fixing only release-critical and important bugs: 5 days
* Other NMUs: 10 days
Those delays are only examples. In some cases (uploads fixing security
issues, trivial bugfixes blocking a transition, ...), it is desirable
that the fixed package reaches unstable sooner.
Sometimes, release managers decide to allow NMUs with shorter delays for
a subset a bugs (e.g release critical bugs older than 7 days). Also,
some maintainers listed themselves in the Low Threshold NMU list, 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 on the BTS before,
or if you know that the maintainer is generally active.
5.11.1.1 NMUs and debian/changelog
Just like any other (source) upload, NMUs must add an entry to
debian/changelog, telling what has changed with this upload. The first
line of this entry is special, it must be
* Non-maintainer upload.
The version must be the version of the last upload, plus +nmuX, where X
is a counter starting at 1. If the last upload was also an NMU, the
counter should be increased. For example, if the current version is
1.5-1, then an NMU would get version 1.5-1+nmu1. If the current version
is 1.5+nmu3 (a native package which has already been NMUd), the NMU
would get version 1.5+nmu4. If a new upstream version is packaged in the
NMU, the debian revision is set to 0, for example 1.6-0+nmu1.
This special versioning 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 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 +debXYuZ should be used,
where X is the current stable major release number, and Y is the current
minor release number for a stable upload, or one higher than that for a
testing upload. Z is a counter starting at 1. For example, while Etch
(Debian 4.0) is stable, a security NMU to stable for a package at
version 1.5-3 would have version 1.5-3+deb40u1, while a security NMU to
Lenny would get version 1.5-3+deb41u1. This is the case even when it is
already known that the next release will be a new major version; for
instance, Lenny will be released as Debian 5.0.
5.11.1.2 Using the DELAYED/ queue
After asking the maintainer for the permission to upload your NMU, it is
annoying to have to wait for some time before you actually make the
upload.
The DELAYED queue (FIXME: link to 5.6.2) allows the developer doing the
NMU to perform all the necessary tasks at the same time. Instead of
telling the maintainer that you will upload the updated package in (for
example) 7 days, you should upload the package to DELAYED/7 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.
The DELAYED 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 (the maintainer
cannot cancel the upload himself).
If you make an NMU to DELAYED, and the maintainer updates his package
before the delay expires, your upload will be rejected, because a newer
version (the maintainer's one) is already available in the archive.
Normally, the maintainer should take care to include your proposed
changes (or at least a solution for the problems they address) in that
upload.
5.11.2 NMUs, from the maintainer's point of view
When someone NMUs your package, this means they want to help you to keep
it in good shape. This saves you work, and gives users fixed packages
faster. You can consider asking the NMUer to become a co-maintainer of
the package.
If someone suggests that they could do an NMU on your package, you
should be thankful that they want to put time into this, while it is
really your responsibility to fix the bug. 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.
When a package has been NMUed, the maintainer should acknowledge it in
the next upload. This makes clear that the changes were accepted in the
maintainer's packaging, and that they aren't lost again. For this, you
must first incorporate the changes into your packaging, by applying the
patch that was sent. Make sure to include the NMU's changelog entry in
your own changelog. This is important to allow the BTS version tracking
to work.
5.11.3 Source NMUs vs Binary-only NMUs (binNMUs)
The full name of an NMU is source NMU. There is also another type,
namely the binary-only NMU, or binNMU. A binNMU is also a package upload
by someone other than the package's maintainer. However, it is a
binary-only upload.
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.
BinNMUs are usually done by porters. They add an entry to
debian/changelog, explaining why the upload was needed and increasing
the version number as described in paragraph 5.10.2.1. This entry should
not be included in the next upload.
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.
5.11.4 NMUs vs QA uploads
NMUs are uploads of packages which are owned by another maintainer.
There is another type of upload where the uploaded package is not yours:
QA uploads. QA uploads are uploads of orphaned packages.
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:
* QA upload.
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. When doing the
first QA upload to an orphaned package, the maintainer should be set to
Debian QA Group < packages@qa.debian.org >. Orphaned packages which did
not have a QA upload yet still have their old maintainer set. There is a
list of them at http://qa.debian.org/orphaned.html.
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 (details here).
=== nmudiff improvements
Currently, nmudiff uses the following default email:
Hi,
The following is the diff for my $SOURCE $VERSION NMU.
It is proposed that this will be changed to:
[Replace XX with correct value]
Dear maintainer,
I prepared an NMU for $SOURCE (versioned as $VERSION) to fix
this bug.
I uploaded it to DELAYED/XX. Please feel free to tell me if I
should delay it longer.
--
$DEBFULLNAME
=== Rationales
= Direct commit using debcheckout
In some cases, the maintainer might allow direct commit to the package's
VCS repository. We felt that it was not a good idea to include this in
the DEP, because:
* there's currently no way for the maintainer to say whether he
wants NMUers to commit their changes or not
* this practice is not in widespread use, as far as we know
* debcheckout isn't documented elsewhere in developer-reference
= the nmudiff patch is not controversial. Why include it in the DEP?
* If the DEP isn't agreed upon, the patch has no reason to be
included in devscripts.
* It gives the opportunity to discuss the formulation at the same
time as the rest of the DEP.
* DEPs are supposed to allow changes in several parts of Debian at
the same time. That's a good test case :-)
= Is that really the best place to discuss stable, security and QA
uploads, and binNMUs?
* It's there in the current version of this chapter.
* Reorganisation of developer-reference is probably a job for the
developer-reference's maintainer, not for us.
=== History
Cosmetic changes are not mentioned here, refer to the wiki page's
history if you need them.
2008-04-28
* Emphasize that example values are examples, and that it's
sometimes desirable to upload sooner.
2008-04-23
* Make NMU versioning match dch.
* Make security versioning less confusing.
* Don't confuse buildd uploads with binNMUs.
* Explicitly require sending a patch to the BTS (and reporting
the bug).
* Don't talk about waiting, but instead specify the DELAYED
queue as the only normal way to do an NMU.
* Added rationale section.
* Added rationale for "no mention of debcheckout"
* Added rationale for inclusion of nmudiff patch.
* Added "default values" for delays.
* Improved introduction.
--
I encourage people to send encrypted e-mail (see http://www.gnupg.org).
If you have problems reading my e-mail, use a better reader.
Please send the central message of e-mails as plain text
in the message body, not as HTML and definitely not as MS Word.
Please do not use the MS Word format for attachments either.
For more information, see http://pcbcn10.phys.rug.nl/e-mail.html
Attachment:
signature.asc
Description: Digital signature