From: aph <aph@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Sat, 22 Feb 2003 20:57:22 +0000 (+0000)
Subject: move bpp-debian-changelog to be right after bpp-debian-control section
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=4bd1fb55987619c54bf47a50c2ab7e846c005d05;p=developers-reference.git

move bpp-debian-changelog to be right after bpp-debian-control section


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

diff --git a/developers-reference.sgml b/developers-reference.sgml
index f56ecd4..063538a 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.181 $">
+  <!entity cvs-rev "$Revision: 1.182 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -3211,6 +3211,150 @@ until that is available.</p>
         </sect1>
       </sect>
 
+
+      <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>
+The changelog entry for a package revision documents changes in that
+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 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"), 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>
+This doesn't tell readers anything too useful, obviously.
+
+          <p>
+<example>
+  * Applied patch from Jane Random.
+</example>
+What was the patch about?
+
+            <p>
+<example>
+  * Late night install target overhaul.
+</example>
+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>
+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.
+</example>
+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.
+</example>
+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
+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>
+Where's the description?  If you can't think of a descriptive message,
+start by inserting the title of each different bug.
+        </sect1>
+      </sect>
+
 <!--
 	<sect1 id="pkg-mgmt-cvs">Managing a package with CVS
 	<p>
@@ -3425,148 +3569,6 @@ Lisp packages should register themselves with
 
       </sect>
 
-      <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>
-The changelog entry for a package revision documents changes in that
-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 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"), 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>
-This doesn't tell readers anything too useful, obviously.
-
-          <p>
-<example>
-  * Applied patch from Jane Random.
-</example>
-What was the patch about?
-
-            <p>
-<example>
-  * Late night install target overhaul.
-</example>
-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>
-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.
-</example>
-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.
-</example>
-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
-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>
-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>