From ae8f11eabe6095df197abdef31e8bbaab7125867 Mon Sep 17 00:00:00 2001
From: hertzog <hertzog@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Mon, 6 May 2002 23:25:59 +0000
Subject: [PATCH] - Changed -e by -m in the dpkg-buildpackage command line. -
 Remove all references explaining that the upstream orig tarball can be  
 changed during lifetime. - Deleted "binary NMU" when we really mean "porter
 upload" or "simple   recompile". - Elaborated more about "binary-only NMU". -
 Detail more things about the removal of package. - Fix other issues from
 #102626.

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1661 313b444b-1b9f-4f58-a734-7bb04f332e8d
---
 debian/changelog          |   6 ++
 developers-reference.sgml | 137 ++++++++++++++++++++++----------------
 2 files changed, 84 insertions(+), 59 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 277b201..89594a7 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -38,6 +38,12 @@ developers-reference (3.0) unstable; urgency=low
     - change some literal quotes to &lsquo;, &rdquo;, etc.
     - update copyright date
     - some simplifications on the TeX suffix rule
+  * Raphael Hertzog:
+    - changed -e by -m in the dpkg-buildpackage command line example.
+      closes: #110310
+    - clarify wording between "porter upload", "binary-only NMU", "simple
+      recompile"; closes: #102626
+    - extended "removing a package"; closes: #135560
 
  -- Adam Di Carlo <aph@debian.org>  Sun,  5 May 2002 17:57:42 -0400
 
diff --git a/developers-reference.sgml b/developers-reference.sgml
index cd78885..061fe12 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.93 $">
+  <!entity cvs-rev "$Revision: 1.94 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -1040,10 +1040,7 @@ may be modified by using <tt>-sa</tt> to always include it or
 If no original source is included in the upload, the original
 source tar-file used by <prgn>dpkg-source</prgn> when constructing the
 <tt>.dsc</tt> file and diff to be uploaded <em>must</em> be
-byte-for-byte identical with the one already in the archive.  If there
-is some reason why this is not the case, the new version of the
-original source should be uploaded, possibly by using the <tt>-sa</tt>
-flag.
+byte-for-byte identical with the one already in the archive.
 
 
 	<sect2 id="upload-dist">Picking a distribution
@@ -1374,10 +1371,10 @@ 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.
        <p>
-Debian porters, who compile packages for different architectures, do
-NMUs as part of their normal porting activity (see <ref
-id="porting">).  Another reason why NMUs are done is when a Debian
-developers needs to fix another developers' packages in order to
+Debian porters, who compile packages for different architectures,
+occasionnaly do binary-only NMUs as part of their porting activity
+(see <ref id="porting">).  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.
@@ -1401,8 +1398,7 @@ Source NMUs always involves changes to the source (even if it is just
 a change to <file>debian/changelog</file>).  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
-(or, more rarely, new upstream source as well).
+architecture-dependent packages, as well as an updated Debian diff.
 	<p>
 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
@@ -1536,12 +1532,6 @@ this, you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the
 <tt>-sa</tt> switch to force the build system to pick up the new
 source package (normally it only looks for Debian revisions of '0' or
 '1' &mdash; it's not yet clever enough to know about `0.1').
-	  <p>
-Remember, porters who are simply recompiling a package for a different
-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.
 
 
 	<sect2 id="nmu-changelog">
@@ -1566,16 +1556,12 @@ few changes to the package as possible, and they should always send a
 patch as a unified context diff (<tt>diff -u</tt>) detailing their
 changes 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 not a porter and 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</package>), there must still be a changelog entry;
-therefore, there will be a patch.  If you are a porter, you are
-probably just doing a binary-only NMU.  (Note: this leaves out in the cold
-porters who have to do recompiles &mdash; chalk it up as a weakness in how
-we maintain our archive.)
+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 <ref id="binary-only-nmu"> 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.
 	  <p>
 If the source NMU (non-maintainer upload) fixes some existing bugs,
 these bugs should be tagged <em>fixed</em> in the Bug Tracking
@@ -1592,13 +1578,14 @@ changes in the NMU are incorporated officially into the package by
 the official package maintainer.
 	  <p>
 Also, after doing an NMU, you have 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.
+patch showing all the changes you have made. Alternatively you can send
+that information to the existing bugs that are fixed by your NMU.
+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.
 	  <p>
 In addition, the normal maintainer should <em>always</em> retain the
 entry in the changelog file documenting the non-maintainer upload.
@@ -1609,8 +1596,7 @@ entry in the changelog file documenting the non-maintainer upload.
 Source NMU packages are built normally.  Pick a distribution using the
 same rules as found in <ref id="upload-dist">.  Just as described in
 <ref id="uploading">, a normal changes file, etc., will be built.  In
-fact, all the prescriptions from <ref id="upload"> apply, including
-the need to announce the NMU to the proper lists.
+fact, all the prescriptions from <ref id="upload"> apply.
 	  <p>
 Make sure you do <em>not</em> change the value of the maintainer in
 the <file>debian/control</file> file.  Your name as given in the NMU entry of
@@ -1633,7 +1619,7 @@ is different from the original architecture of the package
 maintainer's binary package.  It is a unique and essential activity.
 In fact, porters do most of the actual compiling of Debian packages.
 For instance, for a single <em>i386</em> binary package, there must be
-a recompile for each architecture, which is amounts to
+a recompile for each architecture, which amounts to
 &number-of-arches; more builds.
 
 
@@ -1664,7 +1650,7 @@ are set properly.  The best way to validate this is to use the
 <package>debootstrap</package> package to create an unstable chroot
 environment.  Within that chrooted environment, install the
 <package>build-essential</package> package and any package
-dependancies mention in <tt>Build-Depends</tt> and/or
+dependencies mention in <tt>Build-Depends</tt> and/or
 <tt>Build-Depends-Indep</tt>.  Finally, try building your package
 within that chrooted environment.
 		<p>
@@ -1712,32 +1698,35 @@ try to run <tt>dpkg-buildpackage -b</tt>.
 	<p>
 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 binary-only NMU so
+that case; it describes how to build and upload your binary package 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 <ref
 id="nmu-guidelines"> instead.
 	<p>
-In a binary-only NMU, no real changes are being made to the source.  You do
+For a porter upload, no changes are being made to the source.  You do
 not need to touch any of the files in the source package.  This
 includes <file>debian/changelog</file>.
 	<p>
 The way to invoke <prgn>dpkg-buildpackage</prgn> is as
-<tt>dpkg-buildpackage -B -e<var>porter-email</var></tt>.  Of course,
+<tt>dpkg-buildpackage -B -m<var>porter-email</var></tt>.  Of course,
 set <var>porter-email</var> to your email address.  This will do a
 binary-only build of only the architecture-dependant portions of the
 package, using the `binary-arch' target in <file>debian/rules</file>.
 
-	<sect2 id="recompile-nmu-versioning">
-          <heading>Recompilation binary-only NMU versioning</heading>
+	<sect2 id="binary-only-nmu">
+          <heading>Recompilation or binary-only NMU</heading>
 	<p>
-Sometimes you need to recompile a package against other packages which
-have been updated, such as libraries.  You do have to bump the version
-number in this case, so that the version comparison system can
-function properly.  Even so, these are considered binary-only NMUs
-&mdash; there is no need in this case to trigger all other
-architectures to consider themselves out of date or requiring
-recompilation.
+Sometimes the initial porter upload is problematic because the environment
+in which the package was built was not good enough (outdated or obsolete
+library, bad compiler, ...). Then you may just need to recompile it in
+an updated environment. However, you do have to bump the version number in
+this case, so that the old bad package can be replaced in the Debian archive
+(<prgn>katie</prgn> refuses to install new packages if they don't have a
+version number greater than the currently available one).  Despite the
+required modification of the changelog, these are called binary-only NMUs
+&mdash; there is no need in this case to trigger all other architectures
+to consider themselves out of date or requiring recompilation.
 	<p>
 Such recompilations require special ``magic'' version numbering, so that
 the archive maintenance tools recognize that, even though there is a
@@ -1774,7 +1763,7 @@ uploaded with <em>no</em> waiting period for the `frozen' distribution.
 	  <p>
 However, if you are a porter doing an NMU for `unstable', the above
 guidelines for porting should be followed, with two variations.
-Firstly, the acceptable waiting period &mdash the time between when the
+Firstly, the acceptable waiting period &mdash; the time between when the
 bug is submitted to the BTS and when it is OK to do an NMU &mdash; is seven
 days for porters working on the unstable distribution.  This period
 can be shortened if the problem is critical and imposes hardship on
@@ -1884,12 +1873,9 @@ belongs in.
 If you need to change the section for one of your packages, change the
 package control information to place the package in the desired
 section, and re-upload the package (see the <url id="&url-debian-policy;"
-name="Debian Policy Manual"> for details).  Carefully examine the
-installation log sent to you when the package is installed into the
-archive.  If for some reason the old location of the package remains,
-file a bug against <tt>ftp.debian.org</tt> asking that the old
-location be removed.  Give details on what you did, since it might be
-a bug in the archive maintenance software.
+name="Debian Policy Manual"> for details). If your new section is
+valid, it will be moved automatically. If it does not, then contact
+the ftpmasters in order to understand what happened.
 	<p>
 If, on the other hand, you need to change the <em>subsection</em> of
 one of your packages (e.g., ``devel'', ``admin''), the procedure is
@@ -1901,10 +1887,23 @@ override file updated, as described in <ref id="override-file">.
       <sect1 id="removing-pkgs">Removing packages
 	<p>
 If for some reason you want to completely remove a package (say, if it
-is an old compatibility library which is not longer required), you
+is an old compatibility library which is no longer required), you
 need to file a bug against <tt>ftp.debian.org</tt> asking that the
 package be removed.  Make sure you indicate which distribution the
-package should be removed from.
+package should be removed from. Normally, you can only have packages
+removed from <em>unstable</em> and <em>experimental</em>.  Packages
+are not removed from <em>testing</em> directly. Rather, they will be
+removed automatically after the package has been removed from
+<em>unstable</em> and no package in <em>testing</em> depends on it.
+	<p>
+You also have to detail the reasons justifying that request. This is to
+avoid unwanted removals and to keep a trace of why a package has been
+removed. For example, you can provide the name of the package that
+supersedes the one to be removed.
+	<p>
+Usually you only ask the removal of a package maintained by yourself.
+If you want to remove another package, you have to get the approval
+of its last maintainer.
 	<p>
 If in doubt concerning whether a package is disposable, email
 &email-debian-devel; asking for opinions.  Also of interest is the
@@ -2008,6 +2007,26 @@ outlining all the open bugs against your packages:
 Replace <var>address</var> with you official Debian
 maintainer address.
 
+      <sect id="submit-bug">Submitting bugs
+	<p>
+Often as a package maintainer, you find bugs in other packages or else
+have bugs reported to your packages which need to be reassigned.  The
+<url id="&url-bts-control;" name="BTS instructions"> can tell you how
+to do this.
+	<p>
+We encourage you to file bugs when there are problems.  Try to submit
+the bug from a normal user account at which you are likely to receive
+mail.  Do not submit bugs as root.
+	<p>
+Make sure the bug is not already filed against a package.  Try to do a
+good job reporting a bug and redirecting it to the proper location.
+For extra credit, you can go through other packages, merging bugs
+which are reported more than once, or setting bug severities to
+`fixed' when they have already been fixed.  Note that when you are
+neither the bug submitter nor the package maintainer, you should
+not actually close the bug (unless you secure permission from the
+maintainer).
+
       <sect1 id="bug-answering">Responding to bugs
 	<p>
 Make sure that any discussions you have about bugs are sent both to
-- 
2.30.2