From 6a001a2df55e80bb86fe797929cd74c11f9773eb Mon Sep 17 00:00:00 2001 From: aph Date: Sat, 21 Nov 1998 18:13:51 +0000 Subject: [PATCH] finish 1st draft filling in NMU/porter chapter git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@731 313b444b-1b9f-4f58-a734-7bb04f332e8d --- debian/changelog | 33 +++- developers-reference.sgml | 404 +++++++++++++++++++++++++------------- 2 files changed, 298 insertions(+), 139 deletions(-) diff --git a/debian/changelog b/debian/changelog index 567ed9a..9c24607 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,19 +1,42 @@ -developers-reference (2.5.0.1) frozen unstable; urgency=low +developers-reference (2.5.0.2) frozen unstable; urgency=low * maintainer name change (but it's still me) + * Ch. "Non-Maintainer Uploads (NMUs) and Porters": new chapter + discussing NMUs and porters; Section "Interim Releases" integrated out + of existance. New TOC for this section is: + * 6 Non-Maintainer Uploads (NMUs) and Porters + + 6.1 Who can do a port or an NMU + + 6.2 When to do a port or an NMU + o 6.2.1 When to do an NMU if you are a porter + + 6.3 How to do an NMU + o 6.3.1 NMU version numbering + o 6.3.2 NMUs must create a changelog entry + o 6.3.3 NMUs must send patches, if any, to the BTS + o 6.3.4 Building the NMU + + 6.4 Guidelines for Porters + * Sec. "Maintainer changes": renamed to "Adopting a package" and moved to Chapter "Moving, Removing, Renaming, Adopting, and Orphaning Packages". - * Ch. "Non-Maintainer Uploads (NMUs) and Porters": new chapter - discussing NMUs and porters; Section "Interim Releases" integrated out - of existance + * Sec. "Reporting lots of bugs at once": more forcefully deprecate this + practice + * Sec. "Adopting a package": mention that the BTS maintainer update can + take a couple of weeks + * Sec. "Overview of Debian Maintainer Tools": give credit where credit + is due and attribute current maintainers; add `apt'; add `quinn-diff'; + add mention of as yet unreleased 'buildd' package, since I'm so + excited about it and can't wait + * Sec. "Removing packages": talk about how apt-cache can be used to look + at reverse depends, a good step to take prior to removing a package + from the archive + * show *full* TOC, including sect2 * of course the obligatory typo, grammar, and spelling corrections * Makefile: small changes to accomodate DDP autobuild * debian/dirs: obsolete, removed * debian/rules: use changelog date for SGML timestamping, not current date - -- A. P. Harris Mon, 16 Nov 1998 03:18:35 -0500 + -- Adam P. Harris Fri, 20 Nov 1998 12:27:53 -0500 developers-reference (2.5.0) frozen unstable; urgency=low diff --git a/developers-reference.sgml b/developers-reference.sgml index f769a2d..ee5b715 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -44,7 +44,7 @@ id="http://www.gnu.org/copyleft/gpl.html" name="the GNU website">. You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - + Scope of This Document

@@ -54,8 +54,8 @@ developers.

The procedures discussed within include how to become a maintainer (); how to upload new packages (); how and when to do interim releases of other -maintainer's packages (); how to move, remove, or orphan +id="upload">); how and when to do ports and interim releases of other +maintainers' packages (); how to move, remove, or orphan packages (); and how to handle bug reports ().

@@ -430,8 +430,8 @@ non-free/source/

As you can see, the top-level directory of the distribution contains -three directories, namely main, contrib, and -non-free. These directories are called sections. +three directories, namely In each section, there is a directory with the source packages (source), a directory for each supported architecture @@ -450,7 +450,7 @@ The Sections

The main section is what makes up the official Debian -GNU/Linux distribution. The . The On the other hand, if we called the distribution directories Debian-x.y from the beginning, people would think that Debian -release x.y is available. (This happened in the past, where a +release x.y is available. (This happened in the past, where a CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development version. That's the reason why the first official Debian release was 1.1, and not 1.0.) @@ -1021,41 +1021,82 @@ For more information about Non-Maintainer Uploads (NMUs) and Porters -

Under certain circumstances it is necessary for someone other than the -usual package maintainer to make a release of a package. This is +official package maintainer to make a release of a package. This is called a non-maintainer upload, or NMU.

Debian porters, who compile packages for different architectures, do -binary NMUs as part of their normal porting activity. Sometimes, -Debian developers do NMUs 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. +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.

This chapter contains information providing guidelines for when and -how NMUs should be done. - - -Who can do an NMU -

-Only official Debian maintainers can do NMUs. -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. - - -When to do an NMU -

-When a security bug is detected a fixed package should be uploaded as -soon as possible. In this case, the Debian Security Managers should -get in 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. +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. + + 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. +

+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 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. + + + Who can do a port or 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 +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. + + + 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. +

+NMU guidelines for when to do an NMU depends on the target +distribution, i.e., stable, unstable, or frozen. +

+Only critical changes or security bugfixes make it into stable. When +a security bug is detected a fixed package should be uploaded as soon +as possible. In this case, the Debian Security Managers should get in +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.

During the release freeze (see ), NMUs which fix important or higher severity bugs are encouraged and accepted. @@ -1064,88 +1105,87 @@ current maintainer of the package; they might be just about to upload a fix for the problem.

Bug fixes to unstable by non-maintainers are also acceptable, but only -as a last resort. Try the following steps first, and if they don't -work, it is ok to do an NMU: +as a last resort or with permission. Try the following steps first, +and if they don't work, it is probably ok to do an NMU:

- -Make sure that the package bug is in the Debian BTS. If not, submit a -bug. - + +Make sure that the package bug is in the Debian Bug Tracking System +(BTS). If not, submit a bug. + 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 Bug Tracking System. - + +Go ahead and fix the bug, submitting a patch to the right bug in the +BTS. + 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 . - + - When to do an NMU if you are a porter -

-Porters who have to patch the source package in order to get the -package to compile need to follow these steps as well, although their -window of time that they should wait is smaller, since they deal with -a high quantity of packages. -

+ When to do an 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. +

Again, the situation will vary depending on the distribution they are -uploading to. Crucial fixes (i.e., changes need to get a source package -to compile) can be uploaded with However, if you are a porter doing an NMU for `unstable', the above -guidelines for porting should be followed, with one variation. -If you need to alter the source of a package in order to get a -released port of Debian to compile, the bug you 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. -

-An acceptable waiting period -- the time between when the bug is -submitted to the BTS and when it is ok to do an NMU -- is ten days -for porters working on the unstable distribution. +guidelines for porting should be followed, with two variations. +Firstly, the acceptable waiting period -- the time between when the +bug is submitted to the BTS and when it is ok to do an NMU -- is ten +days for porters working on the unstable distribution. +

+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 -that can't be helped. If you have to kluge around compilers bugs and -the like, make sure you #ifdef your work properly; also, +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. +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. -How to do an NMU - + How to do an NMU +

This section applies to NMUs, but not, necessarily, to porters. -A distinction is made between a ).

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

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

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

If you are doing a non-maintainer upload (NMU), you should add a new minor version number to the 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 made by an NMU. -

-If there is no dpkg-buildpackage with the +

+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 there is no 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. -NMUs must create a changelog entry -

+ + NMUs must create a changelog entry +

A non-maintainer doing an 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. -NMUs must send patches, if any, to the BTS -

-Maintainers other than the usual package maintainer should make as few -changes to the package as possible, and they should always send a + + NMUs must send patches, if any, to the BTS +

+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 @@ -1219,18 +1262,54 @@ 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. -

+

In addition, the normal maintainer should Guidelines for Porters + + Building the NMU +

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

+Make sure you do debian/control file. Your name from the NMU entry of the +debian/changelog file will be used for signing the changes +file. + + + Guidelines for Porters +

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

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

+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 Moving, Removing, Renaming, Adopting, and Orphaning Packages + Moving, Removing, Renaming, + Adopting, and Orphaning Packages

Some archive manipulation operation are not automated in the Debian -upload process. This chapter gives guidelines in what to do in these +upload process. These procedures should be manually followed by +maintainers. This chapter gives guidelines in what to do in these cases. Moving packages @@ -1262,8 +1341,11 @@ package be removed. Make sure you indicate which distribution the package should be removed from.

If in doubt concerning whether a package is disposable, email -apt-cache showpkg +/var/cache/apt/pkgcache.bin , the program will show +details for Replacing or renaming packages

@@ -1302,14 +1384,14 @@ If you wish to take over maintenance of any of the packages listed in 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 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 -Reporting lots of bugs at once

+Reporting a great number of bugs for the same problem on a great +number of different packages -- i.e., more than 10 -- is a deprecated +practice. Take all possible steps to avoid submitting bulk bugs at +all. For instance, if checking for the problem can be automated, add +a new check to If you report more then 10 bugs on the same topic at once, it is recommended that you send a message to Note that when sending lots of bugs on the same subject, you should @@ -1395,7 +1484,8 @@ go about with their duties of maintainership. Nor is it meant to endorse any particular tool to the exclusion of a competing tool.

Most of the descriptions of these packages come from the actual -package descriptions themselves. +package descriptions themselves. Further information can be found in +the package documentation itself. +This package is maintained by Ian Jackson and the + and . +

+This package is maintained by Richard Braakman. +This package is maintained by Joey Hess. debstd, which incorporates in one big shot the same sort of automated functions that one finds in +This package is maintained by Santiago Vila. +This package is maintained by Manoj Srivastava. +This package is maintained by Heiko Schlittermann. + + + + + +This package is maintained by James Troup. + + + + +The +We are very excited about this system, since it potentially has so +many uses. Independant development groups can use the system for +different sub-flavors of Debian, which may or may not really be of +general interest (for instance, a flavor of Debian built with gcc +bounds checking). It will also enable Debian to recompile entire +distributions quickly. -- 2.30.2