X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=pkgs.dbk;h=2fb760965e038b2cdeb3ef18b0821d700c78ea96;hp=c6c478cea7d01c8bb7adf5de5a083b49277ea27d;hb=430f868ef5cabbf6539d3051966de888d14277be;hpb=197ca95697c6fa103bfb7c63b4ebbe0059b5e216 diff --git a/pkgs.dbk b/pkgs.dbk index c6c478c..2fb7609 100644 --- a/pkgs.dbk +++ b/pkgs.dbk @@ -1829,325 +1829,315 @@ role="package">ftp.debian.org
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. - - -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 . If a buildd builds and uploads a package, that -too is strictly speaking a binary NMU. See for -some more information. - - -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. - - -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. - - -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 +Non-Maintainer Uploads (NMU). +
-How to do a NMU - -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. - - -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. - +When and how to do an NMU + -A NMU should follow all conventions, written down in this section. For an -upload to testing or unstable, this -order of steps is recommended: +Before doing an NMU, consider the following questions: -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. -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? -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. ). 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. -Upload your package to incoming in DELAYED/7-day (cf. - ), 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). -Follow what happens, you're responsible for any bug that you introduced with -your NMU. You should probably use (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. -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 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 +nmudiff script in the devscripts package +might be helpful. -For the testing 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 testing is through -unstable. +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 +debian/README.source. -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 +DELAYED queue). Here are some recommended values to use for delays: + + -When a security bug is detected, the security team may do an NMU, using their -own rules. Please refer to for more -information. +Upload fixing only release-critical bugs older than 7 days: 2 days + + -For the differences for Porters NMUs, please see . +Upload fixing only release-critical and important bugs: 5 days + + -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 -
+ + -
-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. +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 unstable sooner. + -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. +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 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 in the BTS +before, or if you know that the maintainer is generally active. + -If there is no debian-revision 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 debian-revision value `0.1'. The usual -maintainer of a package should start their -debian-revision 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). + -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-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.
-Source NMUs must have a new changelog entry +NMUs and debian/changelog -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. - - -By convention, source NMU changelog entries start with the line +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 must explicitely mention that this upload is an NMU, e.g.: - * Non-maintainer upload + * Non-maintainer upload. -
-
-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. +The version must be the version of the last maintainer 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 NMUed), 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. + + + +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. + -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 - 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 ++debXYuZ +should be used, where X and +Y are the major and minor release numbers, and +Z is a counter starting at 1. +When the release number is not yet known (often the case for +testing, 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 1.5-3 would have version +1.5-3+deb40u1, whereas a security NMU to Lenny would get +version 1.5-3+deb50u1. After the release of Lenny, security +uploads to the testing distribution will be versioned ++deb51uZ, 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 +deb60uZ. +
+ +
+Using the <literal>DELAYED/</literal> queue + -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 DELAYED queue (see ) +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 +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. + -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 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 since the +maintainer cannot cancel the upload himself. + -In addition, the normal maintainer should always 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 DELAYED 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. +
-
-Building source NMUs +
+NMUs from the maintainer's point of view + -Source NMU packages are built normally. Pick a distribution using the same -rules as found in , follow the other -instructions in . +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. + -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. +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. +
-
-Acknowledging an NMU +
+Source NMUs vs Binary-only NMUs (binNMUs) + -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 --v option of dpkg-buildpackage, 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 closes: #nnnn in the changelog -entry of your next upload. +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. + -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 ). +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. -
-
-NMU vs QA uploads -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 . If you perform an NMU on an -improperly orphaned package, please set the maintainer to Debian QA Group -<packages@qa.debian.org>. +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 . +This entry should not be included in the next upload. -
-
-Who can do an NMU -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. +
-
-Terminology +
+NMUs vs QA uploads + -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. +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. + -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. +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. + + -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 Debian QA Group +<packages@qa.debian.org>. Orphaned packages which did +not yet have a QA upload still have their old maintainer set. There is a list +of them at . + -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 ). +
@@ -2285,7 +2275,7 @@ available in unstable, but not affecting the version in It must be available on all architectures on which it has previously been built -in unstable. may be of interest +in unstable. may be of interest to check that information;