Re: changelog format

[Stefano Lattarini]

On 05/24/2012 12:47 PM, Thien-Thi Nguyen wrote:
> () Stefano Lattarini <address@hidden>
> () Thu, 24 May 2012 11:30:15 +0200
> 
>    > 3 -- (dependent on points 1 and 2) Endorse the changelog as the *best*
>    >      place for rationale/why information for: [...]
> 
>    IMHO, this misses the most important scenario where comments in a
>    ChangeLog entries are justified (I'd say required): explaining the
>    *why* of a *change*.  See my lengthy explanations in:
> 
>      <http://lists.gnu.org/archive/html/bug-standards/2012-05/msg00000.html>
>      <http://lists.gnu.org/archive/html/bug-standards/2012-05/msg00009.html>
> 
>    the main point that can be condensed from there being:
> 
>      The how and why the code works the way it works -- yes, that must
>      definitely must go in code comments (albeit in most cases, placing
>      also an "abridged" version in the commit message as well won't hurt).
>      But the rationale of why a change is needed, and how it relates to
>      previous changes or attempts -- that must go in the commit messages
>      (albeit in some cases, reporting part of that history in code comments
>      can be of great help).
> 
> I don't agree that it's required
>
There's a misunderstanding here.  I'm not saying that the rationale should
be *mandated*, as in some cases it is truly overkill; for example, in a
commit message like this:

    security: use fgets, not gets; the latter is dangerous!

    * input.c (MAXLEN): New #define.  Maximal length of our input lines.
    (foo, bar, baz): Don't call gets(2); instead, call fgets(2), with a
    size parameter of MAXLEN.

adding a "rationale" paragraph is probably overkill; it could be done:

    security: use fgets, not gets; the latter is dangerous!

    Since it is impossible to tell without knowing the data in advance how
    many characters  gets() will read, and because gets() will continue to
    store characters past the end of the buffer, it is extremely dangerous
    to use.

    * input.c (MAXLEN): New #define.  Maximal length of our input lines.
    (foo, bar, baz): Don't call gets(2); instead, call fgets(2), with a
    size parameter of MAXLEN.

but I wouldn't feel like mandating it.

What I'm saying is that, *when* a rationale about the why and how of a
changeset is to be given, the proper place for it is the commit message;
so, *when* it's needed, it *must* go in the commit message.

> (since the overall thrust is to edge ever so slightly;
>
Agreed, let's take baby steps.

> the "and why" is not universally highly valued).
>
Which is real a shame.

> Thus, i considered this rationale to be weaker than the others for this
> particular spate of changes (that is, whereas the other reasons describe
> clear(er) need, this one describes good practice).
> 
> That said, given ‘s/must/could/3’ and slight reworking, i think that
> paragraph would be a good candidate for the intro blurb, once we finish
> this (conservative, remember "ever so slightly") round.  (Translation:
> I sympathize but wish to focus scope, to ratchet results and move on.)
>
OK.

>    > Overall, the thrust is to edge ChangeLog files outward from strictly
>    > "what changed" ever so slightly towards "what changed and why", in the
>    > process making it easier to *follow* a chain of "what changed".
> 
> Note that i do mention "and why".
>
I noticed :-)

Thanks,
  Stefano