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.  Also, you are exgagerating, very few handle it specially.  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, 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.

   >    + @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.  Simply say "For other circumstances the
change log is the best place.".

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

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

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

   >    + @item give credit
   >    + It is courteous to acknowledge the help of others.  Although such
   >    + information may be available indirectly through a URL, including it
   >    + in the change log fosters community spirit and makes it more
   >    + self-contained.
   >    + @end table
   > 
   > I don't think ChangeLog shouldn't be used to give credit, that is what
   > AUTHORS and then THANKS files are used for;

   But the ChangeLog let you register *why* are you giving credit.
   For example, in Automake, the policy is to list any "helping
   person" in THANKS (with full name and associated e-mail address),
   and then cite it (full name only)

You can do similar in THANKS.

  Stefano Lattarini: Added numerous tast cases, ....

This is more consice, and easier to look at.

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

     "Report and initial patch by Zack Weinberg, test cases added by
      Stefano Lattarini."

Since this was an actual patch, this should be part of the CL header,
not as a note, like so (if it isn't copyright significant):

2111-11-11  Zack Weinberg  <...> (tiny change)

And if it is, and you had to rewrite it, then the format could (I'd
write would, but I realised only some projects do this) be:

2111-11-11  Zack Weinberg  <...>
            Stefano Lattarini <...>

Or some such.  The CL header should state who _wrote_ the change; not
who commited it.  Thus there is no need to mention a thank you for
patches, or suggestions since this information is already handled
elsewhere.

   >    ***************
   >    *** 3544,3550 ****
   >      Here are some simple examples of change log entries, starting with the
   >      header line that says who made the change and when it was installed,
   >      followed by descriptions of specific changes.  (These examples are
   >    ! drawn from Emacs and GCC.)
   > 
   >      @example
   >      1998-08-17  Richard Stallman  <rms@@gnu.org>
   >    --- 3561,3567 ----
   >      Here are some simple examples of change log entries, starting with the
   >      header line that says who made the change and when it was installed,
   >      followed by descriptions of specific changes.  (These examples are
   >    ! drawn from Emacs and GCC, from back when the title was optional.)
   > 
   > Making it the description line mandatory is definitly a bad idea.

   FWIW, I *strongly* disagree.

Which makes it more prudent to make it optional; since everyone will
have a differnt opinion on it.  The maintainer can decide if it should
be mandatory or not for per project.