Re: changelog format

[Stefano Lattarini]

On 01/17/2012 10:16 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.

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

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

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?  Are you just dropping an hack
for an obsolete system?  I can't say by reading that CL.  Something as simple as
this would have solved all these doubts and potential misunderstandings:

  Unconditionally assume malloc and friends are declared in <stdlib.h>

  That now holds for every non-museum system.  So stop checking for the 
<malloc.h>
  header, as well as including it: this compatibility workaround is no more 
needed.

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

>    >    + @table @asis
>    >    + @item describe motivation
>    >    + A change conceptually has three parts: before, why and after.
>    >    + ``Before'' and ``after'' are captured in the version control system,
>    >    + but where to capture ``why'' depends on what changed.  When source
>    >    + code changes in a small number of files, the best place for ``why'' 
> is
>    >    + in the comments.  For other circumstances---many files or changes to
>    >    + files that do not support a comment syntax---the change log is the
>    >    + best place.
>    > 
>    > I would skip the `many files, no comment syntax' part, or atleast
>    > the `no comment' bit since such files are not very common, and it
>    > is trivial to preprocess them through grep or sed allowing for
>    > comments.
> 
>    I don't understand your point here.  Could you rephrase it (and maybe
>    even provide an example for clarification)?  Thanks.
> 
> I find the "many files or changes to files that do not support a
> comment syntax" to be redundant, if you have a file format that cannot
> handle comments, it is easy to work around it, allowing for better
> documentation of the program.
>
Ah, ok then.

(Still, maybe it would be worth explicitly stating that if you have a deep
change that touches several files in an intricate or non-obvious way, you
might not be able to explain the reason behind this change or the new
behaviour it implements in code comments scattered among some or even all
of those files -- you must do so in the CL instead.  But this can be left
for a later discussion).

> Simply say "For other circumstances the change log is the best place.".
>
I agree that for this first round this is good enough.  Improvements and
expansions can be done in a follow up patch (if we'll feel the need for
them).

>    >    + @item link to external resources
>    >    + This includes bug report or mailing list URLs.
>    > 
>    > I would suggest: "This includes bug report IDs, URLs to related
>    > mailing list threads, etc.".  Citing the URL to a bug report is
>    > generally bad, since it might change.
> 
>    I agree.  But notice that the issue you are describing is not that
>    bad in practice: the URL to a bug report almost surely contains the
>    number or ID of the report, which you can easily extract for
>    yourself even once the URL has become invalid.
> 
> 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).

> (bug#10260) is clickable, and the way to reference the bug report
> stored in .dir-locals.el.  There is also already precedence for this;
> emacs, gcc, gdb, binutils, coreutils.  Inventing, or changing how
> things are done is hard, specially if they are for the worse.
>
Fair enough.  If you want to propose a further enhancement preaching
against the dangers of using URLs instead of IDs to refer to bug reports,
I will happily praise it and back it up :-)

>    > Personally I am not fond of citing the mailing list thread, such
>    > information should be distilled and put into comments, or
>    > documentation.
> 
>    I generally agree, but sometimes you can condensate only so much of a
>    given discussion in a code comment or commit message; in which case,
>    having a partial-but-readable explanation in the VCS *and* a link to
>    the original discussion is the best middle-ground.
> 
> Maybe we can suggest that one should prefer commenting over using a
> URL then.
>
I'd heartily agree *if the these two things were mutually exclusive*.
But they are not: you can distillate a good rationale and put in the
comments and/or in the ChangeLog entry, *and also* add a symlink to
the original discussion at the same time.  Another example from the
Automake ChangeLog:

    progs, libs: implement EXTRA_foo_DEPENDENCIES

    Backported from commit `v1.11-377-g6edafbb'.

    The feature implemented by that change is quite unobtrusive, so
    adding it to a maintenance release is acceptable.  Also, there
    have been requests from real-world users for this feature since
    it has been implemented in master; see automake bug#9320:
     <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=9320>
    and this short discussion on the automake list:
     <http://lists.gnu.org/archive/html/automake/2010-11/msg00099.html>
    It would be a pity to make such users wait even more (until
    Automake 1.12 is out) before they could start using this feature.
    Thus we backport it, so that it will appear in the next maintenance
    version of automake (1.11.3).

Of course, you could explicitly state that adding a link to a mailing list
discussion as a shortcut to avoid writing a good CL entry (or worse, proper
code comments) is a big huge no-no.  I agree 100% with that.

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

> [SNIP]

I'll try to reply to the rest of your mail tomorrow.

Thanks,
  Stefano