Re: Another changelog rant
On Wed, Jul 18, 2001 at 03:34:09PM +0200, Josip Rodin wrote:
> On Tue, Jul 17, 2001 at 09:18:49PM -0400, Matt Zimmerman wrote:
> > I understand what the (Closes: #bug) syntax is for; I use it all the time.
> > It is meant to complement proper changelog entries, to automatically close
> > bugs. It is not a substitute for listing the changes that were made.
> >
> > bad: "Applied patch from Joe Schmo (Closes: #bug) bad: "Modified the
> > configuration file (Closes: #bug)
> >
> > good: "Applied patch from Joe Schmo to warve the fleeble option (Closes:
> > #bug) good: "Commented out the brillig directive in /etc/blarg.conf
> > (Closes: #bug)"
> >
> > Persons reading the changelog should not have to access the BTS in order to
> > learn what changes were actually made to the package.
>
> You misunderstood my post: I meant that what you are suggesting fits in the
> developers' reference because doing changelog entries that relate to bugs is
> already described there.
Ah, OK. I guess a note there would be appropriate, but it would be best if
that note could reference another section which describes how to write good
changelog entries.
...and there it is, staring me in the face under "Packaging Considerations"
(aka miscellaneous) in the Policy Manual. 5.3 debian/changelog.
Here is my suggested edit:
--- policy.sgml~ Fri Jun 1 05:40:16 2001
+++ policy.sgml Wed Jul 18 15:04:53 2001
@@ -2235,6 +2235,17 @@
</footnote>
</p>
+ <p>It is important to give a meaningful description of the
+ changes made to the package, so that users and other
+ developers can understand how these changes will affect them.
+ This description should make sense even if the reader does
+ not have access to external information (such as the
+ messages archived by the Bug Tracking System).
+ Specifically, if a bug is closed by this upload, the
+ changelog should list the changes that were made in order to
+ fix the bug, not merely the fact that the bug was closed.
+ </p>
+
<p>
The maintainer name and email address used in the changelog
should be the details of the person uploading <em>this</em>
--
- mdz
Reply to: