Re: changelog format

[Stefano Lattarini]

Hi Alfred.

On 01/17/2012 08:44 PM, Alfred M. Szmidt wrote:
>    *** a/doc/standards.texi
>    --- b/doc/standards.texi
>    ***************
>    *** 3516,3531 ****
>      to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
>      @kbd{C-x v a} (@code{vc-update-change-log}) does the job.
> 
>    - There's no need to describe the full purpose of the changes or how
>    - they work together.  However, sometimes it is useful to write one line
>    - to describe the overall purpose of a change or a batch of changes.  If
>    - you think that a change calls for explanation, you're probably right.
>    - Please do explain it---but please put the full explanation in comments
>    - in the code, where people will see it whenever they see the code.  For
>    - example, ``New function'' is enough for the change log when you add a
>    - function, because there should be a comment before the function
>    - definition to explain what it does.
> 
> Why is this section removed?
> 
>      In the past, we recommended not mentioning changes in non-software
>      files (manuals, help files, etc.) in change logs.  However, we've been
>      advised that it is a good idea to include them, for the sake of
>    --- 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.  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.

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

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

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

>    + @item link to another entry
>    + This is useful when a change is a fix or continuation
>    + of a previous change.
> 
> What does `another entry' mean in this context?  Another ChangeLog
> entry?
>
>    + @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)
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."

> see the GNU Maintainer
> Guide for details.  Or at least, it shouldn't be encouraged as the
> place for saying thank you.
> 
>      @node Style of Change Logs
>      @subsection Style of Change Logs
>    ***************
>    *** 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.

>      @example
>      1998-08-17  Richard Stallman  <rms@@gnu.org>
>    ***************
>    *** 3609,3614 ****
>    --- 3626,3664 ----
> 
>      As for the date, that should be the date you applied the change.
> 
>    + In the short paragraph, URLs should have angle braces and (non-patch)
>    + credits may optionally exclude the contributor's email address.  (A
>    + patch should be handled as described above.)  
> 
> ")." over ".)" please :-)
> 
>    A link to another entry
>    + should be expressed as a date and an optional title, if the date is
>    + insufficient to uniquely identify the precedent.  We recommend this
> 
> What about "A reference to another entry should be expressed as a date
> and optionally a title if the date is insuficient to uniquely identify
> the reference."
> 
>    + over using a version control system commit identifier for two
>    + reasons: if the project changes version control systems, then those
>    + identifiers will dangle uselessly; and using a date (and maybe title)
>    + makes the change log self-contained.
>    + 
>    + Whether or not to add extra blank lines around the short paragraph is
>    + up to you.  If so, each group of changes should have its own heading.
>    + (In Emacs, set @code{add-log-always-start-new-record} to @code{t}.)
>    + 
>    + Likewise, what constitutes the title is up to you.
>    + We note here only that many projects use the form:
>    + @var{topic}[, @address@hidden: @var{description}.
> 
> I'm really against making the description line mandatory, but if that
> would be the case it must have a fixed format and not be ad-hoc.  Then
> one can make Emacs insert such a line.
>
The problem is that various projects are still using different formats,
and me and Thien-Thi thought that forcing on them a "Unique, Definitive,
Better-than-thou" format right away wasn't a great move.  Maybe we might
suggest a preferred format, and make it mandatory in the future, once
(and if) it really catches on.  But all of this can be discussed in a
follow-up IMHO.

> I would like to see more examples, examples are really good source to
> put your mind at reset.
>
> Nice job.
> 

Regards,
  Stefano