Re: changelog format

[Alfred M. Szmidt]

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

   > 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_!

   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.

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

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