X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=ad12c3baac6aad80e4c2b664a7b3eb1352a39cbe;hb=59bedc813bc4de304ab2c0116e2ffcd86d951383;hp=1a90106b878eb407169ca059c4b12efdf9047ef7;hpb=34de8a86363cbd42d2b922ad28349830a0255f1e;p=developers-reference.git

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 1a90106..ad12c3b 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.170 $">
+  <!entity cvs-rev "$Revision: 1.175 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -514,7 +514,7 @@ all the files.
 There are other additional channels dedicated to specific subjects.
 <em>#debian-bugs</em> is used for coordinating bug squash parties.
 <em>#debian-boot</em> is used to coordinate the work on the boot
-floppies (i.e. the installer). <em>#debian-doc</em> is
+floppies (i.e., the installer). <em>#debian-doc</em> is
 occasionally used to talk about documentation, like the document you are
 reading. Other channels are dedicated to an architecture or a set of
 packages: <em>#debian-bsd</em>, <em>#debian-kde</em>, <em>#debian-jr</em>,
@@ -1447,6 +1447,8 @@ contains a new upstream version of the software looks like this:
 There are tools to help you create entries and finalize the
 <file>changelog</file> for release &mdash; see <ref id="devscripts">
 and <ref id="dpkg-dev-el">.
+	  <p>
+See also <ref id="bpp-debian-changelog">.
 
 
     <sect id="upload">Package uploads
@@ -1481,6 +1483,9 @@ to emit errors (they will start with <tt>E</tt>).
 		<p>
 For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
 	      <item>
+Optionally run <ref id="debdiff"> to analyze changes from an older version,
+if one exists.
+	      <item>
 Downgrade the package to the previous version (if one exists) &mdash; this
 tests the <file>postrm</file> and <file>prerm</file> scripts.
 	      <item>
@@ -2138,9 +2143,9 @@ fix can break seemingly unrelated features in subtle ways.
 Review and test your changes as much as possible.  Check the
 differences from the previous version repeatedly
 (<prgn>interdiff</prgn> from the <package>patchutils</package> package
-and <prgn>debdiff</prgn> from <package>devscripts</package> are useful tools for
-this).
-
+and <prgn>debdiff</prgn> from <package>devscripts</package> are useful
+tools for this, see <ref id="debdiff">).
+<p>
 When packaging the fix, keep the following points in mind:
 
 <list>
@@ -2419,13 +2424,17 @@ Make sure that your <tt>Build-Depends</tt> and
 <tt>Build-Depends-Indep</tt> settings in <file>debian/control</file>
 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
+environment (see <ref id="debootstrap">).
+Within that chrooted environment, install the
 <package>build-essential</package> package and any package
 dependencies mentioned in <tt>Build-Depends</tt> and/or
 <tt>Build-Depends-Indep</tt>.  Finally, try building your package
 within that chrooted environment.  These steps can be automated
 by the use of the <prgn>pbuilder</prgn> program which is provided by
-the package of the same name.
+the package of the same name (see <ref id="pbuilder">).
+		<p>
+If you can't set up a proper chroot, <prgn>dpkg-depcheck</prgn> may be
+of assistance (see <ref id="dpkg-depcheck">).
 		<p>
 See the <url id="&url-debian-policy;" name="Debian Policy
 Manual"> for instructions on setting build dependencies.
@@ -3131,9 +3140,15 @@ to the user about a package before they install it.  It should provide
 all the required information to let the user decide whether to install
 the package.
 	    <p>
-For consistency and aesthetics, you should capitalize the first letter
-of the Synopsis.  Don't put a full stop (period) at the end.  The
-description itself should consist of full sentences.
+The following practices supplement the <url name="Policy on the descriptions
+of packages" id="&url-debian-policy;ch-miscellaneous.html#s-descriptions">.
+	    <p>
+The synopsis line (the short description) should primarily be concise.
+You may capitalize the first letter for aesthetics. It is customary to
+make the synopsis an appositive clause (not a full sentence) in which
+case there's no need to put a full stop (period) at the end.
+	    <p>
+The long description should, however, always consist of full sentences.
 	    <p>
 Since the first user impression is based on the description, be
 careful to avoid spelling and grammar mistakes. Ensure that you
@@ -3386,6 +3401,135 @@ 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 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>
+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>
+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>
+<example>
+  * Fixed all outstanding bugs.
+</example>
+	<p>
+This doesn't tell readers anything too useful, obviously. Don't do that(TM).
+
+<example>
+  * Applied patch from Jane Random.
+</example>
+	<p>
+What was the patch about?
+
+<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?
+
+<example>
+  * Fix vsync FU w/ ancient CRTs.
+</example>
+	<p>
+Too many acronyms, and it's not overly clear what the fuckup (oops,
+a curse word!) was actually about, or how it was fixed.
+
+<example>
+  * 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.
+
+<example>
+  * 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
+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).
+
+<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.
+
+
 
   <chapt id="beyond-pkging">
     <heading>Beyond Packaging</heading>
@@ -3641,7 +3785,7 @@ with <example>debsign -m"<var>FULLNAME</var> <var>email-addr</var>" <var>changes
 before uploading it to the incoming directory.
 	<p>
 The Maintainer field of the <file>control</file> file and the
-<file>changelog</file> should list the person who did the packaging, i.e. the
+<file>changelog</file> should list the person who did the packaging, i.e., the
 sponsoree. The sponsoree will therefore get all the BTS mail about the
 package. 
 	<p>
@@ -3766,8 +3910,33 @@ packages at <url id="&url-lintian;">. Those reports contain the latest
 <package>lintian</package> but has a different set of checks.  Its
 written in Python rather than Perl.</p>
         </sect1>
+
+        <sect1 id="debdiff">
+          <heading><package>debdiff</package></heading>
+          <p>
+<prgn>debdiff</prgn> (from the <package>devscripts</package> package)
+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
+in the control file. Of course, some of the changes it reports will be
+all right, but it can help you prevent various accidents.
+	  <p>
+You can run it over a pair of binary packages:
+<example>
+debdiff package_1-1_arch.deb package_2-1_arch.deb
+</example>
+	  <p>
+Or even a pair of changes files:
+<example>
+debdiff package_1-1_arch.changes package_2-1_arch.changes
+</example>
+	  <p>
+For more information please see <manref name="debdiff" section="1">.
+        </sect1>
+
       </sect>
 
+
       <sect id="tools-helpers">
         <heading>Helpers for <file>debian/rules</file></heading>
 	<p>
@@ -4016,6 +4185,29 @@ directory of your package.  For instance, when editing
 <file>debian/changelog</file>, there are handy functions for
 finalizing a version and listing the package's current bugs.</p>
         </sect1>
+
+        <sect1 id="dpkg-depcheck">
+          <heading><package>dpkg-depcheck</package></heading>
+          <p>
+<prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package> package)
+runs a command under <prgn>strace</prgn> to determine all the packages that
+were used by the said command.
+	  <p>
+For Debian packages, this is useful when you have to compose a
+<tt>Build-Depends</tt> line for your new package: running the build
+process through <prgn>dpkg-depcheck</prgn> will provide you with a
+good first approximation of the build-dependencies. For example:
+<example>
+dpkg-depcheck -b debian/rules build
+</example>
+	  <p>
+<prgn>dpkg-depcheck</prgn> can also be used to check for run-time
+dependencies, especially if your package uses exec(2) to run other
+programs.
+	  <p>
+For more information please see <manref name="dpkg-depcheck" section="1">.
+        </sect1>
+
       </sect>