<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.170 $">
+ <!entity cvs-rev "$Revision: 1.171 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
There are tools to help you create entries and finalize the
<file>changelog</file> for release — see <ref id="devscripts">
and <ref id="dpkg-dev-el">.
+ <p>
+See also <ref id="bpp-debian-changelog">.
<sect id="upload">Package uploads
</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.").
+Exception can be made if the comment is funny ;-) Obviously, this is
+subjective, so it's likely best if 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>
~ianmdlvl / developers-reference.git / commitdiff