Re: changelog format
On Thu, Sep 01, 2005 at 12:30:41AM -0400, Andres Salomon wrote:
> Argh.
>
> 2.6.12-6's changelog is awful; there are multiple types of styles in there.
> Can we *please* have some consistency in the changelog entries? The format
> that we've used for ages has been:
>
> * <description> (<author>) (closes: <bug#>)
>
> If the fix is a security or arch-specific fix, it's been:
> * [<arch>] <description> (<author>) (closes: #<bug#>)
>
> Sometimes we include patches:
> * <patch1>, <patch2>
> <desc> (<author>)
>
> And for large changes:
> * <desc>
> o <subdesc1>
> o <subdesc2> [<CVE entry>]
>
>
> ..and so on. Now we've decided to throw in:
> [<author>]
> * <desc>
> (closes: #<bug#>) (<authors>)
> Why are we listing authors twice? And why doesn't anyone else think
> that looks absolutely horrid (putting the author first), emphasizing
> who did the change, rather than the change itself.
Well, we have not decided, the first [<author>] is thrown in by dch, and
people are still using the same format as always, and maybe not always remove
the [<author>] bit.
Notice that the [<author>] part will probably become a standard all among
debian as dch enforces it, so maybe it is worthwhile thinking about it.
The current format was chosen back then since it was deemed more important to
have a history of the changes in the changelog, complete with chronological
info, than grouping the entries by author. I guess this makes sense given our
development model, since we work together, and the package is not a group of
changes from various people assembled together to do the release.
The simple way is to erase the [<author>] part, as soon as you notice them,
and check over the changelog bbefore release, or to follow the new dch way:
> While I think the above is ugly, I would be happy w/ *consistency* if
> we decide on that. I'm going to propose the following for changelog
> entries. Whatever we decide on, can we please attempt to stick to
> the same style?
>
> For packaging related changes:
>
> * <desc> (closes: #<bug#)
> (<author>)
>
> My reasoning for the above: bug closings are closely related to the
> description, so they should be next to each other.
Agreed.
> For patch related changes:
> * <patchname>:
> <desc> (closes: #<bug#>)
> (<author>)
>
> For large patches (ie, 2.6.12.6):
> * <patchname>:
> <desc>
> o <subdesc1> (closes: #<bug#>)
> o <subdesc2>
> (<author>)
>
> Multiple patches, if related, can be separated by commas. If the desc
> is very short (ie, because the patch name is descriptive), you can put
> the patchname and desc on the same line:
>
> * <patchname>: Added (closes: #<bug#>)
> (<author>)
>
> Architecture-specific changes should have their description line start
> with [<arch>]. The arch should be in all lowercase.
> Security fixes should have their description line start
> with [SECURITY] (reasoning: the fact that it's a security fix takes
> precedence over what arch if affects; if it really is a fix that affects
> only one arch, just mention that in the description somewhere). Security
> fixes that have CVE entries/CAN numbers should have their description line
> start with [SECURITY: <CAN>].
What about [SECURITY,<arch>] ?
> Changelog entries should be separated by a newline.
>
> Here's 2.6.12-6 following the above convention:
>
> * Change ATM and Classical-IP-over-ATM to be modular, instead of being
> statically included (closes: #323143).
> (Andres Salomon, Bastian Blank)
>
> * powerpc-apus.patch:
> Added preliminary apus patch, not applied though.
> (Sven Luther)
>
> * powerpc-pmac-sound-check.patch: Added.
> (Sven Luther)
>
> * [i386] Unset CC_OPTIMIZE_FOR_SIZE in i386 config,
> it breaks iproute's (and other netlink users) ability
> to set routes. (closes: #322723)
> (Simon Horman)
>
> * [SECURITY: CAN-2005-2457] 2.6.12.5.patch:
> CAN number added, as patch contains zlib deflateBound() fix.
> (Someone Who Forgot To Put Their Name)
>
> (NOTE for the above: instead of doing that, I would just edit the
> original 2.6.12.5 changelog entry, adding the CAN# to it.)
>
> * 2.6.12.6.patch: Added
> o [SECURITY: CAN-2005-2555] Restrict socket policy loading to
> CAP_NET_ADMIN.
> o [SECURITY] Fix DST leak in icmp_push_reply(). No CAN# assigned
> yet; possible security hole.
> o [SECURITY]: NPTL signal delivery deadlock fix; local DoS.
> o fix gl_skb/skb type error in genelink driver in usbnet.
> o [SECURITY]: fix a memory leak in devices seq_file implementation;
> possible local DoS.
> o [SECURITY]: Fix SKB leak in ip6_input_finish(). Possible resource
> exhaustion DoS.
> (Another Person)
>
> -- Bastian Blank <waldi@debian.org> Fri, 19 Aug 2005 14:39:16 +0200
>
>
> There's my recommendations. Thoughts? Comments?
I like it.
Friendly,
Sven Luther
Reply to: