Re: changelog format

[Stefano Lattarini]

Hi Karl.

On 05/25/2012 12:43 AM, Karl Berry wrote:
>     *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.
> 
> 1) [required] the wording must be such as to not assume/require the
> existence of commit logs or shared source repositories at all.
>
Sloppy wording on my part; I was using "commit message" and "ChangeLog
entry" interchangeably, because in many relevant GNU projects the
ChangeLog file is generated from the git commits messages (which
are thus written so that they obey the GCS recommendations about
ChangeLogs).

> GNU/rms have never required any particular development methodology,
> and (in my experience) he will reject out of hand any attempt to
> impose such.
> 
> In other words, add "if commit logs are used" to the beginning of your
> whole thing.
>
Or better again, refer to "ChangeLog entries" only :-)

Then we might add other advice stating that it's OK, even recommended,
to generate ChangeLogs from the VCS history, in case that is used (and
in which case, of course, the commit messages are to be written so
that they obey the CGS recommendations for ChangeLog entries).  But
this is for a later patch anyway.

> 
> 2) [my opinion] I'm not sure I agree with the idea.  It is one way of
> working, but not the only way.  For myself, I tend to write the
> technical descriptions (including rationale :) in the ChangeLog, and
> make the commit msg be just a one line hint kind of thing.
>
I'd find this a perfectly acceptable practice as well, assuming the
ChangeLog modification take place in the same commit whose changes
it describe (so that they remain properly coupled).

> I actually find that more useful when looking back at the commit
> logs than the full rationales and details.
>
Matter of tastes I presume.  The important thing, which I hope you
agree with, is that the rationale for a non-trivial change must be
spelled out explicitly *and coupled with the change itself*; whether
that is done with a commit message or a ChangeLog modification isn't
really important then.

> I realize full well that other people do other things, and that is fine.
> Perhaps even your way should be recommended.  I don't think my way is so
> horrible that it should be forbidden, however.
>
Agreed; we should find a wording that makes clear your way is acceptable
as well.

> Aside from anything
> else, it would be contrary to all but the most recent and "advanced"
> practice.
> 
> karl

Regards,
  Stefano