Differences between revisions 8 and 9
Revision 8 as of 2008-03-07 10:52:59
Size: 9041
Comment:
Revision 9 as of 2008-03-13 11:35:58
Size: 10242
Editor: ?BasWijnen
Comment: Add paragraph about binNMUs, plus some minor rewordings.
Deletions are marked like this. Additions are marked like this.
Line 17: Line 17:
Line 19: Line 20:
 1. NMUs are often received with angry comments from maintainers.    1. NMUs are often received with angry comments from maintainers.
Line 25: Line 25:
Line 29: Line 28:
NMUs usually happens when someone wants to fix a bug
Line 34: Line 32:
 * Do you really fix bugs in your NMU? Fixing cosmetic issues, or changing the packaging style in NMUs is discouraged, unless it's required to fix bugs.
* 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.
Line 38: Line 37:
In most cases, the above points should not make you reconsider doing an NMU. Fixing bugs is what really matters (but only real bugs, and only really fixing them).
Line 39: Line 39:
In most cases, the above points should not make you reconsider doing an NMU. Fixing bugs is what really matters (but only real bugs, and only really fixing them). While there are no general rules, after the patch is available in the BTS, and you mention your intention to upload an NMU, it's recommended to wait at least one week before doing the upload.
Line 41: Line 41:
While there are no general rules,after the patch is available on the BTS, and you mention your intention to upload an NMU, it's recommended to wait at least one week before making the upload.

Sometimes, release managers decide to allow NMU with shorter delays,
for a subset a bugs (e.g release critical bugs older than 7 days). Also, some maintainers listed themselves in the [http://wiki.debian.org/LowThresholdNmu Low Threshold NMU list], and accept that NMUs are uploaded without delay. But even in that case, 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.
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 [http://wiki.debian.org/LowThresholdNmu Low Threshold NMU list], and accept that NMUs are uploaded without delay. But even in that case, 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.
Line 50: Line 47:

The version of the changelog entry must be the upstream version, plus a Debian revision. However, the debian revision should be of the form '''x.y''', where '''x''' is one less than the next to be released normal Debian revision number for this upstream version, and '''y''' is a counter starting at 1. For example, if the current version is '''1.5-3''', then an NMU would get '''1.5-3.1''' for the version. If a new upstream version is packaged in the NMU, the version would become '''1.6-0.1'''. If there is no debian-revision component in the version number then one should be created, starting at `0.1'.
The version of the changelog entry must be the upstream version, plus a Debian revision. However, the debian revision should be of the form '''x.y''', where '''x''' is one less than the next to be released normal Debian revision number for this upstream version, and '''y''' is a counter starting at '''1'''. For example, if the current version is '''1.5-3''', then an NMU would get '''1.5-3.1''' for the version. If a new upstream version is packaged in the NMU, the version would become '''1.6-0.1'''. If there is no debian-revision component in the version number then one should be created, starting at '''0.1'''.
Line 55: Line 51:
If you upload a package to testing or stable, sometimes, you need to "fork" the version number tree. For this, version numbers like 1.1-3etch0.1 could be used.  If you upload a package to testing or stable, sometimes, you need to "fork" the version number tree. For this, version numbers like 1.1-3etch0.1 could be used.
Line 60: Line 56:
Line 63: Line 58:
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 (example) 7 days, upload the package to DELAYED/7, and tell the maintainer that he has 7 days to react, and tell you to delay the upload some more or cancel your 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 can 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.
Line 67: Line 62:
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. 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.
Line 79: Line 74:
FIXME: explain the difference. 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. There are some reasons why this can be useful:

 * Buildds upload packages for their architecture to the archive as binary-only uploads. Strictly speaking, these are binNMUs.
 * 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 and buildds. 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.
Line 89: Line 88:
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.

Title: Clarifying policies and workflows for Non Maintainer Uploads (NMUs)
DEP: FIXME
State: DRAFT
Date: 2008-02-12
Drivers: Lucas Nussbaum <lucas@debian.org>,
 Bas Wijnen <wijnen@debian.org>
URL: http://wiki.debian.org/NmuDep
Abstract:
 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.

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
  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 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? Did you make your patch available to the maintainer? For how long? 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?
  • Did you make it perfectly clear that you would upload an NMU? Just sending a patch to the BTS doesn't mean that you would do an NMU.
  • 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 (but only real bugs, and only really fixing them).

While there are no general rules, after the patch is available in the BTS, and you mention your intention to upload an NMU, it's recommended to wait at least one week before doing the upload.

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 [http://wiki.debian.org/LowThresholdNmu Low Threshold NMU list], and accept that NMUs are uploaded without delay. But even in that case, 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 of the changelog entry must be the upstream version, plus a Debian revision. However, the debian revision should be of the form x.y, where x is one less than the next to be released normal Debian revision number for this upstream version, and y is a counter starting at 1. For example, if the current version is 1.5-3, then an NMU would get 1.5-3.1 for the version. If a new upstream version is packaged in the NMU, the version would become 1.6-0.1. If there is no debian-revision component in the version number then one should be created, starting at 0.1.

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 you upload a package to testing or stable, sometimes, you need to "fork" the version number tree. For this, version numbers like 1.1-3etch0.1 could be used.

FIXME: We don't fix bug #437392 here.

5.11.1.2 Using the DELAYED/ queue

After asking the maintainer for the permission to upload your NMU, it is often 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 can 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 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.

In the past, bugs fixed in NMUs were tagged fixed in the BTS, and you had to use the -v option of dpkg-buildpackage to include the NMU's changelog entry in the .changes files. This is no longer necessary.

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. There are some reasons why this can be useful:

  • Buildds upload packages for their architecture to the archive as binary-only uploads. Strictly speaking, these are binNMUs.
  • 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 and buildds. 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.

5.11.4 NMUs vs QA uploads

NMUs are uploads of packages which are owned by another maintainer. There is another type of uploading a package which is not yours: a QA upload. This is an upload of an orphaned package.

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

nmudiff improvements

FIXME: propose new wording for the default template to make it more friendly