From: aph <aph@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Sat, 22 Feb 2003 20:51:20 +0000 (+0000)
Subject: s|bugs.debian.org|&bugs-host;|
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=commitdiff_plain;h=e63de6119053a4ac8892093cb8055bb1c86904f1

s|bugs.debian.org|&bugs-host;|
s|<email>control@bugs.debian.org</email>|&email-bts-control;|

<sect1>When bugs are closed by new uploads -- minor editorial changes

<sect>Best practices for debian/changelog -- substantial editing,
although mostly editorial, few content changes

in "Tools", debdiff and dpkg-depcheck link to their package, devscripts


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

diff --git a/common.ent b/common.ent
index 88eee83..e33f6c2 100644
--- a/common.ent
+++ b/common.ent
@@ -147,7 +147,7 @@
 <!entity email-ftpmaster "<email>ftpmaster@debian.org</email>">
 <!entity email-override "<email>override-change@debian.org</email>">
 <!entity email-wnpp "<email>wnpp@debian.org</email>">
-<!entity email-bts-control "<email>control@bugs.debian.org</email>">
+<!entity email-bts-control "<email>control@&bugs-host;</email>">
 <!entity email-security-team "<email>team@security.debian.org</email>">
 
 <!-- misc Debian info -->
@@ -159,7 +159,7 @@
 <!entity file-debian-private-archive "~debian/archive/debian-private/">
 <!entity file-bpp-autotools "<file>/usr/share/doc/autotools-dev/README.Debian.gz</file>">
 
-<!entity cron-bug-report '0 17 * * fri   echo "index maint <var>address</var>" | mail request@bugs.debian.org'>
+<!entity cron-bug-report '0 17 * * fri   echo "index maint <var>address</var>" | mail request@&bugs-host;'>
 
 <!entity control-file-fields "<list compact>
 	      <item><tt>Format</tt>
diff --git a/developers-reference.sgml b/developers-reference.sgml
index 514962d..f56ecd4 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.180 $">
+  <!entity cvs-rev "$Revision: 1.181 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -590,14 +590,14 @@ id="submit-bug"> for information on how to submit bugs.
 
       <sect1 id="servers-bugs">The bugs server
 	<p>
-<tt>bugs.debian.org</tt> is the canonical location for the Bug Tracking
+<tt>&bugs-host;</tt> is the canonical location for the Bug Tracking
 System (BTS).  If you plan on doing some statistical analysis or
 processing of Debian bugs, this would be the place to do it.  Please
 describe your plans on &email-debian-devel; before implementing
 anything, however, to reduce unnecessary duplication of effort or
 wasted processing time.
 	<p>
-All Debian developers have accounts on <tt>bugs.debian.org</tt>.
+All Debian developers have accounts on <tt>&bugs-host;</tt>.
 
       <sect1 id="servers-ftp-master">The ftp-master server
 	<p>
@@ -622,7 +622,7 @@ bugs against the <package>nonus.debian.org</package> pseudo-package (notice
 the lack of hyphen between "non" and "us" in the pseudo-package name
 &mdash; that's for backwards compatibility). Remember to check whether or
 not someone else has already reported the problem on the
-<url id="http://bugs.debian.org/nonus.debian.org" name="Bug Tracking System">.
+<url id="http://&bugs-host;/nonus.debian.org" name="Bug Tracking System">.
 
       <sect1 id="servers-www">The www-master server
 	<p>
@@ -634,7 +634,7 @@ If you find a problem with the Debian web server, you should generally
 submit a bug against the pseudo-package,
 <package>www.debian.org</package>. Remember to check whether or not someone
 else has already reported the problem on the
-<url id="http://bugs.debian.org/www.debian.org" name="Bug Tracking System">.
+<url id="http://&bugs-host;/www.debian.org" name="Bug Tracking System">.
 
       <sect1 id="servers-people">The people web server
 	<p>
@@ -1301,8 +1301,7 @@ various commands to <email>pts@qa.debian.org</email>.
   the list of available keywords:
   <list>
   <item><tt>bts</tt>: mails coming from the Debian Bug Tracking System
-  <item><tt>bts-control</tt>: reply to mails sent to
-        <email>control@bugs.debian.org</email>
+  <item><tt>bts-control</tt>: reply to mails sent to &email-bts-control;
   <item><tt>summary</tt>: automatic summary mails about the state of a package
   <item><tt>cvs</tt>: notification of CVS commits
   <item><tt>ddtp</tt>: translations of descriptions and debconf templates
@@ -1838,7 +1837,7 @@ have bugs reported to your packages which need to be reassigned.  The
 to do this.  Some information on filing bugs can be found in <ref
 id="submit-bug">.
 
-      <sect1>Monitoring bugs
+      <sect1 id="bug-monitoring">Monitoring bugs
 	<p>
 If you want to be a good maintainer, you should periodically check the
 <url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
@@ -1866,16 +1865,16 @@ maintainer address.
 	<p>
 Make sure that any discussion you have about bugs are sent both to
 the original submitter of the bug, and the bug itself (e.g.,
-<email>123@bugs.debian.org</email>). If you're writing a new
+<email>123@&bugs-host;</email>). If you're writing a new
 mail and you don't remember the submitter email address, you can
-use the <email>123-submitter@bugs.debian.org</email> email to
+use the <email>123-submitter@&bugs-host;</email> email to
 contact the submitter <em>and</em> to record your mail within the
 bug log (that means you don't need to send a copy of the mail to
-<email>123@bugs.debian.org</email>).
+<email>123@&bugs-host;</email>).
 	<p>
 Once you've dealt with a bug report (e.g. fixed it), mark it as
 <em>done</em> (close it) by sending an explanation message to
-<email>123-done@bugs.debian.org</email>. If you're fixing a bug by
+<email>123-done@&bugs-host;</email>. If you're fixing a bug by
 changing and uploading the package, you can automate bug closing as
 described in <ref id="upload-bugfix">.
 	<p>
@@ -1892,7 +1891,7 @@ other packages. The bug tracking system's features interesting to developers
 are described in the <url id="&url-bts-devel;" name="BTS documentation for
 Debian developers">. Operations such as reassigning, merging, and tagging
 bug reports are described in the <url id="&url-bts-control;" name="BTS
-control bot documentation">. This section contains
+control server documentation">. This section contains
 some guidelines for managing your own bugs, based on the collective
 Debian developer experience.
         <p>
@@ -1969,15 +1968,15 @@ read <ref id="upload-bugfix">.
 
       <sect1 id="upload-bugfix">When bugs are closed by new uploads
 	<p>
-If you fix a bug in your packages, it is your responsibility as the
-package maintainer to close the bug when it has been fixed.  However,
+As bugs and problems are fixed your packages, it is your
+responsibility as the package maintainer to close the bug.  However,
 you should not close the bug until the package which fixes the bug has
 been accepted into the Debian archive.  Therefore, once you get
 notification that your updated package has been installed into the
 archive, you can and should close the bug in the BTS.
 	<p>
 However, it's possible to avoid having to manually close bugs after the
-upload -- just list the fixed bugs in your <file>debian/changelog</file>
+upload &mdash; just list the fixed bugs in your <file>debian/changelog</file>
 file, following a certain syntax, and the archive maintenance software
 will close the bugs for you. For example:
 
@@ -1990,33 +1989,35 @@ acme-cannon (3.1415) unstable; urgency=low
   * Added man page. Closes: #98725.
 </example>
 
-Technically speaking, the following Perl regular expression is what is
-used:
+Technically speaking, the following Perl regular expression describes
+how bug closing changelogs are identified:
 <example>
   /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
 </example>
 
-The author prefers the <tt>closes: #<var>XXX</var></tt> syntax, as
-one of the most concise and easiest to integrate with the text of the
+We prefer the <tt>closes: #<var>XXX</var></tt> syntax, as it is the
+most concise entry and the easiest to integrate with the text of the
 <file>changelog</file>.
 	<p>
-If you happen to mistype a bug number or forget one in the changelog file,
-don't hesitate to undo any damage the error caused. To reopen wrongly closed
-bugs, send an <tt>reopen <var>XXX</var></tt> command in the bug tracking
-system's control bot. To close any remaining bugs that were fixed by your
-upload, email the <file>.changes</file> file to
-<email>XXX-done@bugs.debian.org</email>, where <var>XXX</var> is your
-bug number.
-	<p>
-Bear in mind that it is not obligatory to close bugs using the changelog
-like described above -- if you simply want to close bugs that don't have
-anything to do with an upload of yours, do it simply by emailing an
-explanation to <email>XXX-done@bugs.debian.org</email>.
-Do <strong>not</strong> close bugs in the changelog entry of a version
-if the said version of the package doesn't have anything to do with the bug.
+If you happen to mistype a bug number or forget a bug in the changelog
+entries, don't hesitate to undo any damage the error caused. To reopen
+wrongly closed bugs, send an <tt>reopen <var>XXX</var></tt> command to
+the bug tracking system's control address, &email-bts-control;.  To
+close any remaining bugs that were fixed by your upload, email the
+<file>.changes</file> file to <email>XXX-done@&bugs-host;</email>,
+where <var>XXX</var> is your bug number.
+	<p>
+Bear in mind that it is not obligatory to close bugs using the
+changelog as described above.  If you simply want to close bugs that
+don't have anything to do with an upload you made, do it by emailing
+an explanation to <email>XXX-done@&bugs-host;</email>.  Do
+<strong>not</strong> close bugs in the changelog entry of a version if
+the changes in that version of the package doesn't have any bearing on
+the bug.
 	  <p>
-For general information on what to put in the changelog files, please
-refer to <ref id="bpp-debian-changelog">.
+For general information on how to write your changelog entries, see
+<ref id="bpp-debian-changelog">.
+
 
       <sect1 id="bug-security">Handling security-related bugs
         <p>
@@ -3424,120 +3425,133 @@ Lisp packages should register themselves with
 
       </sect>
 
-    <sect id="bpp-debian-changelog">
+      <sect id="bpp-debian-changelog">
 	<heading>Best practices for <file>debian/changelog</file></heading>
         <p>
 The following practices supplement the <url name="Policy on changelog
 files" id="&url-debian-policy;ch-docs.html#s-changelogs">.</p>
 
 	<sect1 id="bpp-changelog-do">
-	    <heading>Writing useful changelog entries</heading>
-	<p>
+          <heading>Writing useful changelog entries</heading>
+          <p>
 The changelog entry for a package revision documents changes in that
-revision, and only them. Concentrate on describing changes you did since
-the last version that are worth mentioning.
-	<p>
-Focus on <em>what</em> was changed; who, how and when are usually less
-important. Having said that, remember to politely attribute people who have
-provided notable help in making the package (e.g. those who have sent in
-patches).
-	<p>
-There's no need to elaborate the trivial and obvious changes. You can also
-aggregate several such changes in one entry. However, don't be overly terse
-if you have undertaken a major change. Be especially clear if there are
-changes that affect the behaviour of the program -- and for further
-explanations, use the <file>README.Debian</file> file.
-	<p>
-Use common English language, one which the majority of viewers can
-understand. Avoid abbreviations, "tech-speak" and jargon when explaining
-changes that close bugs, especially if the said bugs were filed by users
-that did not strike you as particularly techically savvy. Also, be polite,
-don't swear.
-	<p>
-It is customary to prefix changelog entries with the names of the files that
-were changed. There's no need to explicitely list each and every last one of
-the changed files, especially if the change was small or repetitive -- use
-wildcard characters wisely.
-	<p>
-When referring to bugs, don't assume anything -- say what the problem was,
-how it was fixed, and append the "closes: #nnnnn" string.
-See <ref id="upload-bugfix"> for more information.
-
-	<sect1 id="bpp-changelog-dont">
-	    <heading>Common misconceptions about changelog entries</heading>
-	<p>
-The changelog entries should <strong>not</strong> document generic packaging
-issues ("Hey, if you're looking for foo.conf, it's in /etc/blah/."), since
-administrators and users are supposed to be at least remotely acquainted
-with how such things are generally arranged on Debian systems. Do, however,
-mention if you change the location of a configuration file.
-	<p>
+revision, and only them. Concentrate on describing significant and
+user-visible changes that were made since the last version.
+          <p>
+Focus on <em>what</em> was changed &mdash; who, how and when are
+usually less important.  Having said that, remember to politely
+attribute people who have provided notable help in making the package
+(e.g., those who have sent in patches).
+          <p>
+There's no need to elaborate the trivial and obvious changes. You can
+also aggregate several changes in one entry.  On the other hand, don't
+be overly terse if you have undertaken a major change.  Be especially
+clear if there are changes that affect the behaviour of the program.
+For further explanations, use the <file>README.Debian</file> file.
+          <p>
+Use common English so that the majority of readers can comprehend it.
+Avoid abbreviations, "tech-speak" and jargon when explaining changes
+that close bugs, especially for bugs filed by users that did not
+strike you as particularly technically savvy.  Be polite, don't swear.
+          <p>
+It is sometimes desirable to prefix changelog entries with the names
+of the files that were changed.  However, there's no need to
+explicitly list each and every last one of the changed files,
+especially if the change was small or repetitive.  You may use
+wildcards.
+          <p>
+When referring to bugs, don't assume anything.  Say what the problem
+was, how it was fixed, and append the "closes: #nnnnn" string.  See
+<ref id="upload-bugfix"> for more information.
+
+
+	<sect1 id="bpp-changelog-misconceptions">
+          <heading>Common misconceptions about changelog entries</heading>
+          <p>
+The changelog entries should <strong>not</strong> document generic
+packaging issues ("Hey, if you're looking for foo.conf, it's in
+/etc/blah/."), since administrators and users are supposed to be at
+least remotely acquainted with how such things are generally arranged
+on Debian systems.  Do, however, mention if you change the location of
+a configuration file.
+          <p>
 The only bugs closed with a changelog entry should be those that are
-actually fixed in the same package revision. Closing bugs unrelated bugs in
-the changelog is considered very bad practice. See <ref id="upload-bugfix">.
-	<p>
+actually fixed in the same package revision.  Closing unrelated bugs
+in the changelog is bad practice. See <ref id="upload-bugfix">.
+          <p>
 The changelog entries should <strong>not</strong> be used for random
-discussion with bug reporters ("I don't see segfaults when starting foo
-with option bar; send in more info.") or pleas for help ("The bug list
-on this package is huge, please lend me a hand."). Such things usually
-won't be noticed by their target audience, but will on the other hand
-annoy people who wish to read information about actual changes in the
-package. Please see <ref id="bug-answering"> for more information on
-how to use the bug tracking system.
-	<p>
-It is an old tradition to acknowledge bugs fixed in non-maintainer uploads
-in the first changelog entry of the real maintainer. You don't have to
-follow it, though: if you are certain that you will include the changes from
-the NMU in your next release, you can simply close the bugs the normal way.
-It's usually polite to note that the bugs were fixed by another developer.
-	<p>
-Changelogs shouldn't include general statements on life, the universe and
-everything ("Sorry this upload took me so long, but I caught the flu.").
-Exceptions can be made if the comment is funny ;-) Obviously, this is
-subjective, so it's likely best if it's kept out of technical documentation
-such as changelogs.
-
-	<sect2 id="bpp-changelog-dont-really-dont">
-	    <heading>Common errors in changelog entries</heading>
-	<p>
+discussion with bug reporters ("I don't see segfaults when starting
+foo with option bar; send in more info"), general statements on life,
+the universe and everything ("sorry this upload took me so long, but I
+caught the flu"), or pleas for help ("the bug list on this package is
+huge, please lend me a hand").  Such things usually won't be noticed
+by their target audience, but may annoy people who wish to read
+information about actual changes in the package.  See <ref
+id="bug-answering"> for more information on how to use the bug
+tracking system.
+          <p>
+It is an old tradition to acknowledge bugs fixed in non-maintainer
+uploads in the first changelog entry of the proper maintainer upload,
+for instance, in a changelog entry like this:
+<example>
+  * Maintainer upload, closes: #42345, #44484, #42444.
+</example>
+This will close the NMU bugs in "fixed" state when the package makes
+it into the archive (and also the bug for the fact that an NMU was
+done).  It is also perfectly acceptable to close NMU-fixed bugs by
+other means; see <ref id="bug-answering">.
+	<p>
+Changelogs shouldn't include general statements on life, the universe
+and everything ("sorry this upload took me so long, but I caught the
+flu").  Exceptions can be made if the comment is funny ;-) Obviously,
+this is subjective, so it's likely best if it's kept out of technical
+documentation such as changelogs.
+        </sect1>
+
+	<sect1 id="bpp-changelog-errors">
+          <heading>Common errors in changelog entries</heading>
+          <p>
+The following examples demonstrate some common errors or example of
+bad style in changelog entries.
+
+          <p>
 <example>
   * Fixed all outstanding bugs.
 </example>
-	<p>
-This doesn't tell readers anything too useful, obviously. Don't do that(TM).
+This doesn't tell readers anything too useful, obviously.
 
+          <p>
 <example>
   * Applied patch from Jane Random.
 </example>
-	<p>
 What was the patch about?
 
+            <p>
 <example>
   * Late night install target overhaul.
 </example>
-	<p>
-Overhaul which accomplished...? Is the mention of late night supposed to
-remind us that we shouldn't trust that code?
+Overhaul which accomplished what?  Is the mention of late night
+supposed to remind us that we shouldn't trust that code?
 
+            <p>
 <example>
   * Fix vsync FU w/ ancient CRTs.
 </example>
-	<p>
-Too many acronyms, and it's not overly clear what the fuckup (oops,
+Too many acronyms, and it's not overly clear what the, uh, fsckup (oops,
 a curse word!) was actually about, or how it was fixed.
 
+            <p>
 <example>
-  * This is not a bug. Closes: #nnnnnn
+  * This is not a bug, closes: #nnnnnn.
 </example>
-	<p>
-First of all, there's absolutely no need to upload the package to convey
-this information. Use the bug tracking system! Secondly, there's no
-explanation as to why the report is not a bug.
+First of all, there's absolutely no need to upload the package to
+convey this information; instead, use the bug tracking system.
+Secondly, there's no explanation as to why the report is not a bug.
 
+            <p>
 <example>
-  * Has been fixed for ages, but I forgot to close. Closes: #54321
+  * Has been fixed for ages, but I forgot to close; closes: #54321.
 </example>
-        <p>
 If for some reason you didn't mention the bug number in a previous changelog
 entry, there's no problem, just close the bug normally in the BTS. There's
 no need to touch the changelog file, presuming the description of the fix is
@@ -3545,13 +3559,15 @@ already in (this applies to the fixes by the upstream authors/maintainers as
 well, you don't have to track bugs that they fixed ages ago in your
 changelog).
 
+            <p>
 <example>
   * Closes: #12345, #12346, #15432
 </example>
-        <p>
-Where's the description?! If you can't think of a descriptive message, start
-by inserting the title of each different bug.
-
+Where's the description?  If you can't think of a descriptive message,
+start by inserting the title of each different bug.
+        </sect1>
+      </sect>
+    </chapt>
 
 
   <chapt id="beyond-pkging">
@@ -3609,7 +3625,7 @@ will help prevent a situation in which several maintainers start
 filing the same bug report simultaneously.
 	<p>
 Note that when sending lots of bugs on the same subject, you should
-send the bug report to <email>maintonly@bugs.debian.org</email> so
+send the bug report to <email>maintonly@&bugs-host;</email> so
 that the bug report is not forwarded to the bug distribution mailing
 list.
 
@@ -3937,7 +3953,7 @@ written in Python rather than Perl.</p>
         <sect1 id="debdiff">
           <heading><package>debdiff</package></heading>
           <p>
-<prgn>debdiff</prgn> (from the <package>devscripts</package> package)
+<prgn>debdiff</prgn> (from the <package>devscripts</package> package, <ref id="devscripts">)
 compares file lists and control files of two packages. It is a simple
 regression test, as it will help you notice if the number of binary
 packages has changed since the last upload, or if something's changed
@@ -4212,7 +4228,8 @@ finalizing a version and listing the package's current bugs.</p>
         <sect1 id="dpkg-depcheck">
           <heading><package>dpkg-depcheck</package></heading>
           <p>
-<prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package> package)
+<prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package> 
+package, <ref id="devscripts">)
 runs a command under <prgn>strace</prgn> to determine all the packages that
 were used by the said command.
 	  <p>