changelog format

[Andres Salomon <dilinger@debian.org>]

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.

And:
  [ <author> ]
  * [<arch>]
    - <desc1>
    - <desc2>


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.

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>].

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?