X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=pkgs.dbk;h=2fb760965e038b2cdeb3ef18b0821d700c78ea96;hb=430f868ef5cabbf6539d3051966de888d14277be;hp=1a86405d841fc0db51840aa899a9034a8bbd2ba2;hpb=0715edeff63f1a6ff6c268a58ca76db9119c94ea;p=developers-reference.git
diff --git a/pkgs.dbk b/pkgs.dbk
index 1a86405..2fb7609 100644
--- a/pkgs.dbk
+++ b/pkgs.dbk
@@ -28,14 +28,18 @@ description of the package, the license of the prospective package, and the
current URL where it can be downloaded from.
-You should set the subject of the bug to ``ITP: foo
--- short description'', substituting the name of the
-new package for foo. The severity of the bug report
-must be set to wishlist. If you feel it's necessary, send
-a copy to &email-debian-devel; by putting the address in the
-X-Debbugs-CC: header of the message (no, don't use
-CC:, because that way the message's subject won't indicate
-the bug number).
+You should set the subject of the bug to ITP:
+foo -- short
+description, substituting the name of the new
+package for foo.
+The severity of the bug report must be set to wishlist.
+Please send a copy to &email-debian-devel; by using the X-Debbugs-CC
+header (don't use CC:, because that way the message's subject won't
+indicate the bug number). If you are packaging so many new packages (>10)
+that notifying the mailing list in seperate messages is too disruptive,
+do send a summary after filing the bugs to the debian-devel list instead.
+This will inform the other developers about upcoming packages and will
+allow a review of your description and package name.
Please include a Closes:
@@ -735,9 +739,9 @@ several developers working on the same package.
-Once a corrected package is available in the unstable
-distribution, you can close the bug. This can be done automatically, read
- .
+Once a corrected package is available in the archive, the bug should be
+closed indicating the version in which it was fixed. This can be done
+automatically, read .
@@ -1825,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 DELAYED/ 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 ).
+
@@ -2281,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;