more work on the NMU/porters chapter

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@728 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 87d1cfefdaad9c29b99daf7e7b0c395f51c27469..f769a2d09a6e191acc26046205095ac17c2c056c 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -11,6 +11,7 @@
   - talk about CVS access, other ways to submit problems
   - add information on how you can contribute w/o being an official
     developer
+  - "official port maintainer" ? (cf. glibc-pre2.1)
  -->
 
   <book>
@@ -1038,7 +1039,11 @@ how NMUs should be done.
 
 <sect id="nmu-who">Who can do an NMU
        <p>
-Only an official Debian developers 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.
 <!-- TODO: link to section talking about how non-maintainers can still
             contribute -->
 
@@ -1121,16 +1126,35 @@ period.
 
 
 <sect id="nmu-guidelines">How to do an NMU
-       <p>
-When someone other than the usual maintainer releases a package they
-should add a new minor version number to the <var/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 <tt>foo_1.1-3.dsc</tt>.  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 <tt>foo_1.1-3.1.dsc</tt>.
+
+This section applies to NMUs, but not, necessarily, to porters.
+A distinction is made between a <em/port/ and an <em/NMU/.  An NMU is
+a fix to a problem with an existing version of a package in an
+archive.  A port is a recompile of a specific revision of a package to
+another port, such that people running the target architecture have
+access to the port.
+       <p>
+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 <ref id="porter-guiddelines">.
+
+<sect1 id="nmu-version">NMU version numbering
+       <p>
+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.
+       <p>
+If you are doing a non-maintainer upload (NMU), you should add a new
+minor version number to the <var/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 <tt>foo_1.1-3.dsc</tt>.  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
+<tt>foo_1.1-3.1.dsc</tt>.
        <p>
 The Debian revision minor number is needed to avoid
 `stealing' one of the package maintainer's version numbers, which might
@@ -1148,41 +1172,60 @@ you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the <tt/-sa/
 switch to force the build system to pick up the new source package
 (normally it only looks for Debian revisions of '0' or '1').
        <p>
-<!-- HERE -->
+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.
+
+<sect1 id="nmu-changelog">NMUs must create a changelog entry
+       <p>
+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.
+
+<sect1 id="nmu-patch">NMUs must send patches, if any, to the BTS
+       <p>
 Maintainers other than the usual package maintainer should make as few
 changes to the package as possible, and they should always send a
-unified context diff (<tt/diff -u/) detailing their changes to the bug
-tracking system.   properly flagged with the correct package so that the
-usual maintainer is kept aware of the situation.
-       <p>
-If the non-maintainer upload (as known as an ``NMU'') fixes some
-existing bugs, the bug reports should not be closed.  Technically,
-only the official package maintainer or the original bug submitter are
-allowed to close bugs. However, the person making the non-maintainer
-release should send a short message to the bug tracking system to all
-the fixed bugs explaining that they have been fixed.  Using
+patch as a unified context diff (<tt/diff -u/) detailing their
+changes, if any, to the bug tracking system.
+       <p>
+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 <package/debhelper/), there <em/will/ be a
+changelog entry; therefore, there will be a patch.
+       <p>
+If the NMU (non-maintainer upload) fixes some existing bugs, the bugs
+which are fixed need to be <em/notified/ but not actually <em/closed/
+by the non-maintainer.  Technically, only the official package
+maintainer or the original bug submitter are allowed to close
+bugs. However, the person making the non-maintainer release must send
+a short message, including the patch for that NMU, to the relevant
+bugs explaining that the bugs have been fixed by the NMU.  Using
 <email/control@bugs.debian.org/, the party doing the NMU should also
 set the severity of the bugs fixed in the NMU to `fixed'.  This
 ensures that everyone knows that the bug was fixed in an NMU; however
 the bug is left open until the changes in the NMU are incorporated
 "officially" into the package by the official package maintainer.
        <p>
-The normal maintainer should do at least one of the following:
-         <list compact>
-           <item>
-apply the diff,
-           <item>
-read the diff and decide on each part of it themselves, or
-           <item>
-if the maintainer decides not to apply the 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.
-         </list>
+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
+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.
        <p>
 In addition, the normal maintainer should <em/always/ include an entry
 in the changelog file documenting the non-maintainer upload.
 
+<sect id="porter-guidelines">Guidelines for Porters
+
+
 
     <chapt id="archive-manip">Moving, Removing, Renaming, Adopting, and Orphaning Packages
       <p>