Re: changelog format

[Stefano Lattarini]

[Quoting all the old message to keep context]
[Sorry for the awful delay]

On 01/21/2012 02:11 PM, Alfred M. Szmidt wrote:
>    >    >    --- 3516,3521 ----
>    >    >    ***************
>    >    >    *** 3536,3541 ****
>    >    >    --- 3526,3558 ----
>    >    >      asterisk, the name of the changed file, and then in 
> parentheses the name
>    >    >      of the changed functions, variables or whatever, followed by a 
> colon.
>    >    >      Then describe the changes you made to that function or 
> variable.
>    >    >    + Each group of related entries should have a @dfn{title}, a one 
> line
>    >    >    + description or summary of the change, and optionally a short
>    >    >    + paragraph to:
>    >    > 
>    >    > I find the wording confusing here, and don't really understand what 
> is
>    >    > optional, or mandatory.  Making the description line (title is
>    >    > confusing) mandatory is bad.  Many changes don't require it.
>    > 
>    >    What?  I'd say that 99% of the changes requires them (all the 
> non-trivial
>    >    changes).  In addition, many modern VCS treat the first line of a 
> commit
>    >    message specially, using it as the "title" of the changeset.  
>    > 
>    > That isn't a case for the description line, we shouldn't depend on what
>    > VCSs do.
> 
>    Why not?  Many GNU projects either autogenerate the ChangeLog from the VCS
>    commit messages, or, even when using a version-controlled ChangeLog, keep
>    each of its entries in sync with the correspondent VCS commit message.  
> This
>    is not a fact that should ignored.  Good and meaningful recommendations 
> have
>    to take existing practice into account.
> 
> Some projects generate the ChangeLog file from commit messages, but
> not that many.  Please don't exaggerate.  Keeping the ChangeLog file
> in sync with the commit messages is hard, sometimes impossible since
> it requires rewriting history
>
How so?

> and you need to do special hacks for it (Jim Meyering has written one
> for git).
> 
>    > Also, you are exgagerating, very few handle it specially.
> 
>    Git does.  Mercurial does.  These alone are enough to steer a decision 
> IMHO.
>    (I think Bazaar as well handles the summary line specially in some 
> respects,
>    but I'm not sure about this).
> 
> That is two, out of several dozen.  Neither CVS nor RCS handle this,
> BZR doesn't either.  I don't think darcs has anything special hacks
> for it.  Those are the ones I use on a daily basis other than git/bzr.
> I know that sccs doesn't handle it, nor does tla.
> 
>    > That is not to say that the description line is not useful, it is, but
>    > forcing it upon everyone isn't the way to go.
>    > 
>    >    So, unless your commit message is exactly one line long, you'll
>    >    need a title line anyway.  At which point you can leave consistency
>    >    win and always require such a title line.
>    > 
>    > Sometimes that is true, sometimes it isn't.  If I rename a function, I
>    > won't write a description,
> 
>    This strikes me as wrong.  Don't you feel the need to explain why
>    you are renaming a function?  Even a simple summary line like:
> 
>      refactor: rename func set_colours to set_colors (we prefer US spelling)
> 
>    immediately makes clear to the reader what the change is about
>    *and* what its reasons are, without forcing it to read anything
>    else (either diffs of the body of the CL).
> 
> Such comments should be in coding guide lines;
>
Even if they are already there, that is no excuse not to explain the reason
for the change in the commit message.  You would still need something like
this:

  refactor: rename func set_colours to set_colors

  As per our guidelines, we prefer US spelling in function and variable names.

  * foo.c, foo.h (set_colours): Renamed ...
  (set_colors): .. to this.
  * All callers: Adjusted accordingly.

Let me stress this, because it is an important point: the fact that a user
could theoretically work out the reason of a change by reading the coding
guidelines or the manual or whatever is *not* in any way a valid excuse
not to explain (or at least summarize) that reason in the commit message
as well.  When explaining things to a human being, "creative" repetition
and some redundancy are a good thing; we are not computers.

> I'd even go as for as
> suggest such an addition to the GCS that American spelling is prefered
> over British.  But I don't feel strongly about it enough.
>
My point wasn't about American vs. British spelling; I just used that
as an example.  We shouldn't get lost in this irrelevant tangent.

>    > but the change might affect many files.
>    > Writing a description would be redundant, the information is already
>    > stored in the body of the CL entry.  Here is another example that
>    > doesn't need a description line:
>    > 
>    > 2011-11-21  Mats Erik Andersson <address@hidden>
>    > 
>    >  * configure.ac: Do not check for <malloc.h>.
>    >  * libinetutils/localhost.c [HAVE_MALLOC_H]: Do not include
>    >  <malloc.h> and delete the conditional.
>    >  * telnet/commands.c [HAVE_MALLOC_H]: Likewise.
>    > 
>    > The CL is clear enough; the description would add little value.
> 
>    I strongly disagree.
> 
>    First, I need to read *all* the ChangeLog entry to just understand what the
>    change is about.  Much worse, even then I can only *guess* at what the 
> reason
>    behind this change is.
> 
> What the change is about is not the purpose of ChangeLog; it describes
> how the code changed.  Not _why_!
>
Then the ChangeLog is mostly useless, and writing it mostly a waste of time.
I'm not the fist one to reach this conclusion:
  <http://gcc.gnu.org/ml/gcc/2007-12/msg00016.html>
  <http://thread.gmane.org/gmane.comp.gcc.devel/94464/>

>    In fact, in this particular case, by reading the above I can't even 
> understand
>    what the change is supposed to do (let alone why it is needed).  Does this 
> change
>    mean that you don't use any function/macro declared in the <malloc.h> 
> header
>    anymore, so the checking for it and the use of it can go away?  Or does it 
> mean
>    that you now unconditionally assume malloc() and friends to be declared in
>    <stdlib.h>, which your C files already include?  
> 
> The entry states it clearly, ./configure no longer checks for
> <malloc.h>; and one doesn't include <malloc.h> in some source files.
> The _why_ of the change is for another place; i.e. in this case coding
> guidelines regarding pre-ANSI C systems.
>
This way, you loose the coupling between the change and the reason behind it.
A better thing to do would: update your coding guidelines, then do your commit
and write something like this in the the commit message:

  cleanup: stop checking for <malloc.h>

  As per our coding guidelines, we can now assume being compiled with a
  conforming ANSI C environmentm, where malloc is declared in <stdlib.h>

  * configure.ac: Do not check for <malloc.h>.
  * libinetutils/localhost.c [HAVE_MALLOC_H]: Do not include
  <malloc.h> and delete the conditional.
  * telnet/commands.c [HAVE_MALLOC_H]: Likewise.

So, a user reading the commit message four years from now will immediately know
why the change was done, and if hew wants to know more details, he will simply
have a look at the (say) 'docs/CodingGuildelines.txt' file as it was in that
same commit.  Clear, efficient, and with no real repetition.  What's wrong with
this?

>    > URL's change, and stop working; this has happened, this will continue
>    > to happen.  The information should be stored in another form, this is
>    > what Emacs does:
>    > 
>    >         * update-subdirs: Don't set no-byte-compile twice (bug#10260).
> 
>    And this is what Automake (of which I'm co-maintainer) does as well :-)
> 
>    My point was only that, in case of URLs to a bug tracker entry, the problem
>    of URL breakage is greatly mitigated by the fact that those URLs are very
>    very likely to contain a reference to the bug ID (which should never 
> break).
> 
> Agreed about the bug ID being unique for each project, simply store
> those in the CL and somehow resolve the ID to a URL through other
> means.
>
>    > Though I am not sure what cases there are that would make
>    > it impossible to put the information in a comment or internal
>    > documentation.  Take Emacs, a big project, if the background for
>    > decisions where in the CL then it would be impossible to get a good
>    > over view of those decisions.  So for that, you have an manual for
>    > emacs internals.
> 
>    This might not be viable for a one-man project.  Especially if the lone
>    maintainer inherits an already-big project lacking such internal
>    documentation.
> 
> Hacking up a simple INTERNALS whatever file is quite simple; I don't
> see the problem.
> 
>    >   Stefano Lattarini: Added numerous test cases, ....
>    > 
>    > This is more concise, and easier to look at.
> 
>    And become unwieldy for users that have contributed with lots of
>    suggestions and bug reports.
> 
> You can prune the line.
> 
>    >    in the relevant ChangeLog entry.  As an example, see some
>    >    excerpts of real ChangeLog entries in Automake:
>    > 
>    >      "Report and suggestions by Peter Rosin and Eric Blake."
>    >      "Reported by Jim Meyering in automake bug#10418."
>    >      "Report and analysis by Paul Eggert."
> 
>    (You haven't said anything about these, so I assume they are good
>    examples).
> 
> Right, I don't use them my self though.
> 
>    > Which makes it more prudent to make it optional; since everyone
>    > will have a differnt opinion on it.
> 
>    But I'm convinced mine is not an opinion, but a *position*
>    motivated by sound technical arguments (see my previous answer for
>    them).  That's why I'm pushing so hard (and will continue to) to
>    make the summary line *unconditionally mandatory*.
> 
> How about a compromise? Make it recommended, but not mandatory.  And
> leave it up to maintainers do decide how hard they wish to enforce the
> policy.
>
Well, I guess that would be better than the present situation where the
summary line is not even recommended.  So OK from me in this respect.

>    > The maintainer can decide if it should be mandatory or not for
>    > per project.
> 
>    IMHO no, not anymore than he can decide whether his project should
>    have a GCS-conforming configure script or not.
> 
> The comparison is not just, ./configure is for the users benefit.
> ChangeLog is for the maintainers and developers.
>

Regards,
  Stefano