From 7bada93452b9d90ecdb93696251b8e976cfb7fd5 Mon Sep 17 00:00:00 2001 From: aph Date: Wed, 25 Nov 1998 10:39:58 +0000 Subject: [PATCH] * Sec. "Removing a package from Incoming": tiny section added * some PGP-centricity removed * Sec. "Adopting a package": point out that hijacking packages is not ok * Ch. "Non-Maintainer Uploads (NMUs) and Porters": change NMU to source NMU, port to binary NMU, shorten the window for porters a tad; fix spelling; stress that non-maintainer patches must be non-disruptive and that aesthetic issues are not suitable for fixing by non-maintainers; other fixes as suggested by interested parties git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@733 313b444b-1b9f-4f58-a734-7bb04f332e8d --- developers-reference.sgml | 311 +++++++++++++++++++++----------------- 1 file changed, 173 insertions(+), 138 deletions(-) diff --git a/developers-reference.sgml b/developers-reference.sgml index ee5b715..7a6bf65 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -217,13 +217,13 @@ must also contain your PGP or RSA public key (extracted using pgp -kxa in the case of PGP) for the database of keys which is distributed from /pub/debian/doc/debian-keyring.tar.gz, or the - Once this information is received and processed, you should be contacted with information about your new Debian maintainer account. If you don't hear anything within 7-14 days, please send a followup -message asking if your original application was received. Do not +message asking if your original application was received. Do Debian porters, who compile packages for different architectures, do -binary NMUs as part of their normal porting activity. Less often, -Debian developers do NMUs for other developers' packages in order to -fix a serious security problem or a crippling bug, especially when the -package maintainer is unable to release a fix in a timely fashion. +NMUs as part of their normal porting activity. 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. It also contains information for when a port -is just a port, or when it is also an NMU, and how these should be -done. +how NMUs should be done. A fundamental distinction is made between +source and binary NMUs, which is explained in the next section. Terminology

-There are two new terms used throughout this section: ``NMU'' and -``port''. These terms are used with specific technical meaning -throughout this document; common parlance may vary. +There are two new terms used throughout this section: ``binary NMU'' +and ``source NMU''. These terms are used with specific technical +meaning throughout this document. Both binary and source NMUs are +similar, since they involve an upload of a package by a developer who +is not the regular maintainer. That is why it's a -Both ports and NMUs are similar, since they involve an upload of a -package by a developer who is not the regular maintainer. In common -parlance, ports are also NMUs since any upload of a package by a -developer who is not the official maintainer is an NMU (i.e., -non-maintainer upload). However, in this chapter, I distinguish -between ports and NMUs artificially in order to keep my meaning clear. -

-An NMU is a upload of a package by a developer who is not the official -maintainer for the purposes of fixing a bug in the package. In my -usage, NMUs always involves changes to the source (even if it is just +A source NMU is a 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.

-A port is a recompilation and upload of a binary packages for a -specific architecture. There are ports where no source changes are -needed and ports where the source has to be changed. In this chapter, -``port'' means a non-maintainer uploaded binary version of a packge -for anther version, with no source changes needed. Of course, there -are many cases where porters must fix problems in the source in order -to get them to compile for their target architecture; however, this -case is considered to be an NMU rather than a port. +A binary NMU is a recompilation and upload of a binary package for a +new architecture. As such, it is part of ``porting''. There are +ports of a package where no source changes are needed and ports where +the source has to be changed. A binary NMU is non-maintainer uploaded +binary version of a package for another architecture, 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 NMU. As you can see, we don't distinguish in terminology +between porters' source NMUs and normal NMUs. +

+Both classes of NMUs, source and binary, 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 I use the unqualified term ``NMU'', I +mean both source and binary NMUs. - Who can do a port or an NMU + Who can do an NMU

-Only official Debian maintainers can do ports or NMUs. This is -because we need to ensure that trojans or other problems are not +Only official Debian maintainers can do binary or source NMUs. This +is because we need to ensure that trojans or other problems are not inserted into the archive. Non-developers, however, are encouraged to -download the source package and start hacking on it to fix problems. -Maintainers almost always appreciate quality patches and bug reports. -Of course there are many other ways that not-yet-official volunteers -can help. +download the source package and start hacking on it to fix problems -- +just submit worthwhile patches to the Bug Tracking System. +Maintainers almost always appreciate quality patches and bug reports +(at least, we hope). - When to do a port or an NMU -

-Porters usually use systems such as ) to tell them what packages need to be compiled for a -given architecture. See for more -information on how to do this type of upload. Porters are always -uploading to either frozen or unstable. + When to do a source NMU

-NMU guidelines for when to do an NMU depends on the target -distribution, i.e., stable, unstable, or frozen. +Guidelines for when to do a source NMU depend on the target +distribution, i.e., stable, unstable, or frozen. Porters have +slightly different rules than non-porters, due to their unique +circumstances (see ).

Only critical changes or security bugfixes make it into stable. When a security bug is detected a fixed package should be uploaded as soon @@ -1096,13 +1095,14 @@ 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, the Security Manager may upload a fixed -package. +package (i.e., do a source NMU).

During the release freeze (see ), NMUs which fix important 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. +a fix for the problem. As with any source NMU, the guidelines found +in 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, @@ -1117,27 +1117,31 @@ 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. +BTS. Build the package and test it as discussed in . Use it locally. Wait a couple of weeks for a response. Email the maintainer, asking if it is ok to do an NMU. -Wait a couple of weeks for a response. - Double check that your patch doesn't have any unexpected side effects. -Build the package and test it as discussed in . +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 . - When to do an NMU if you are a porter + + When to do a source NMU if you are a porter

-Porters doing an NMU as well -- i.e., if the source needs changing -- -generally follow the above guidelines, just like normal NMUs. -However, it is expected that the wait cycle for a porter NMU is -smaller than normal, since porters have to cope with a high quantity -of packages. +Porters doing a source NMU generally follow the above guidelines, just +like non-porters. However, it is expected that the wait cycle for a +porter's source NMU is smaller than for a non-porter, since porters +have to cope with a large quantity of packages.

-Again, the situation will vary depending on the distribution they are +Again, the situation varies depending on the distribution they are uploading to. Crucial fixes (i.e., changes need to get a source package to compile for a released-targetted architecture) can be uploaded with -Secondly, porters doing NMUs should make sure that the bug they submit -to the BTS should be of severity `important' or greater. This ensures -that a single source package can be used to compile every supported -Debian architecture by release time. -

-Try to avoid patches which simply kluge around bugs in the current -version of the compile environment, kernel, or libc. Sometimes such -kluges can't be helped. If you have to kluge around compilers bugs -and the like, make sure you #ifdef your work properly; also, -document your kluge so that people know to remove it once the external -problems have been fixed. +Secondly, porters doing source NMUs should make sure that the bug they +submit to the BTS should be of severity `important' or greater. This +ensures that a single source package can be used to compile every +supported Debian architecture by release time. It is very important +that we have one version of the binary and source package for all +architecture in order to comply with many licenses. +

+Porters should try to avoid patches which simply kluge around bugs in +the current version of the compile environment, kernel, or libc. +Sometimes such kluges can't be helped. If you have to kluge around +compilers bugs and the like, make sure you #ifdef your work +properly; also, document your kluge so that people know to remove it +once the external problems have been fixed.

Porters may also have an unofficial location where they can put the results of their work during the waiting period. This helps others running the port have the benefit of the porter's work, even during -the waiting period. Of course such waiting periods have no official -blessing from Debian. +the waiting period. Of course, such locations have no official +blessing or status, so buyer, beware. - How to do an NMU -

-This section applies to NMUs, but not, necessarily, to porters. -Remember that we are making a distinction between a ). + How to do a source NMU

The following applies to porters insofar as they are playing the dual -role of being both NMU bug-fixers and porters. If a porter has to -change the Debian source archive, automatically their upload is an NMU -and is subject to its rules. If a porter is simply uploading a port, -the rules are different; see . - - - NMU version numbering +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 . +

+First and foremost, it is critical that NMU patches to source should +be as non-disruptive as possible. Do not do housekeeping task, change +the name of modules, move directories, or fix things which are not +broken. Keep the patch as small as possible. If thing bother you +aesthetically, talk to the Debian maintainer, talk to the upstream +maintainer, or submit a bug. However, aesthetic changes must 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 actually work. +to function.

If you are doing a non-maintainer upload (NMU), you should add a new minor version number to the foo_1.1-3.1.dsc.

-The Debian revision minor number is needed to avoid `stealing' one of +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. @@ -1210,70 +1221,80 @@ usual maintainer of a package should start their dpkg-buildpackage with the Remember, porters who are simply recompiling a package for a different -architecture do not need to renumber. Porters should use new NMU -version numbers if and only if they actually have to modify the source -package in some way. +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. - NMUs must create a changelog entry + Source NMUs must have a new changelog entry

-A non-maintainer doing an NMU must create a 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 + - NMUs must send patches, if any, to the BTS + 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 ( 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 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 -If the NMU (non-maintainer upload) fixes some existing bugs, the bugs -which are fixed need to be The normal maintainer will either apply the patch or employ an alternate method of fixing the problem. Sometimes bugs are fixed -independantly upstream; which is another good reason to back out an +independantly 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, read the description of the changes to -the next upstream version and ensure that they fix each problem that -was fixed in the non-maintainer release. +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 Building the NMU + Building source NMUs

-NMU packages are built normally. Pick a distribution using the same -rules as found in . Just as described in , a normal changes file, etc., will be built. In fact, -all the presecriptions from apply, including the -need to announce the NMU to the proper lists. +Source NMU packages are built normally. Pick a distribution using the +same rules as found in . Just as described in +, a normal changes file, etc., will be built. In +fact, all the prescriptions from apply, including +the need to announce the NMU to the proper lists.

Make sure you do debian/control file. Your name from the NMU entry of the @@ -1281,27 +1302,25 @@ Make sure you do Guidelines for Porters + Guidelines for porters (binary NMUs)

If the package builds out of the box for the architecture to be ported to, you are in luck and your job is easy. This section applies to -that case; it describes how to build and upload your NMU so that it is -properly installed into the archive. If you do have to patch the -package in order to get it to compile for the other architecture, read - instead. +that case; it describes how to build and upload your binary NMU so +that it is properly installed into the archive. If you do have to +patch the package in order to get it to compile for the other +architecture, you are actually doing a source NMU, so consult instead.

-Since no real changes are being made to the source, you do not need to -touch any of the files in the source package. This includes -debian/changelog. +In a binary NMU, no real changes are being made to the source. You do +not need to touch any of the files in the source package. This +includes debian/changelog.

The way to invoke dpkg-buildpackage -B -m. Of course, set debian/rules file, resorting to dpkg-buildpackage --b -m is also acceptable. But remember to file -a bug against the package that the binary-arch target in debian/rules. Moving, Removing, Renaming, @@ -1347,6 +1366,13 @@ package. When invoked as apt-cache showpkg /var/cache/apt/pkgcache.bin , the program will show details for Removing packages from +If you decide to remove a package from Replacing or renaming packages

Sometimes you made a mistake naming the package and you need to rename @@ -1385,6 +1411,15 @@ the WNPP, or if you can no longer maintain a packages you have, or you simply want to know if any one is working on a new package, send a message to +It is not ok to simply take over a package that you feel is neglected +-- that would be package hijacking. You can, of course, contact the +current maintainer and ask them if you may take over the package. +However, without their assent, you may not take over the package. +Even if they ignore you, that is still not grounds to take over a +package. If you really feel that a maintainer has gone AWOL (absent +without leave), post a query to + If you take over an old package, you probably want to be listed as the package's official maintainer in the bug system. This will happen automatically once you upload a new version with an updated -- 2.30.2