Re: ChangeLog formatting?

[Oliver Kiddle <okiddle@xxxxxxxxxxx>]

Bart Schaefer wrote:
> 
> Should we agree on some "rules" for ChangeLog entries?

> 
> We're particularly inconsistent about how we credit other contributors (I'm
> guilty of this too).  Examples:
>
>         * 15562, Akinori Musha: 15559, 15563: Completion/BSD/Command/_chflags,

I would vote for this format for credited contributions. By putting the
name before message numbers, it can be inferred that the first message
number was by whomever committed the change without their having to
repeat their own name. First names only should be suffcient for the
usual suspects (as is common at the moment) and e-mail addresses are
perhaps more information than anyone will ever use.

>         * Adapted from Stefan Dalibor, 16043: Src/utils.c: checkrmall()
>         must not print to shout when shout's not valid.

Here, it looks like the contributed change was modified slightly in a
way that is too insignificant to post. So we need a way to cover this.

> With respect to different reasons for different files, most of the time the
> files are still all listed together after the article, and the descriptions
> are all grouped together as well, and it's up to the reader to figure out
> which ones go together.  I only found one previous example of breaking up
> the list of files:

Splitting these as per the example more often is perhaps a good idea
then.

> Finally, as you can see from the above, examples, we're also inconsistent
> about capitalization, whether there is a newline after the colon at the
> end of the list of file names, and at what column the lines should wrap,
> but those are much less significant details.

My votes here are for wrapping so the maximum line is 79 characters. No
newline after the colon unless it could only be followed by about one
word before wrapping at the line end, no initial capitalisation to
avoid the temptation to capitalise the first letter of a function name.
If we don't capitalise, then no final full-stop for consistency with
that. As you say though, these issues are less significant so I don't
care much and will happily defer to anyone else's suggestions.

We could also agree on the format of notes added to cvs - some notes
are preceded by the message number and a colon while others are
followed by the message numbr in brackets.

Oliver