Re: changelog format

[Stefano Lattarini]

Hi Thien-Thi.

On 05/24/2012 11:15 AM, Thien-Thi Nguyen wrote:
> () address@hidden (Karl Berry)
> () Wed, 23 May 2012 22:29:31 GMT
> 
>    The more and smaller pieces there are, with the most concise (and
>    convincing :) possible rationale, the more likely he will accept a
>    change.  (Of course, changes that are truly interdependent and don't
>    make sense separately should be presented together as one change.
>    I'm not talking about technical hunks in a diff.)
> 
> Thanks for the reminder (and to everyone for their patience).  Perhaps
> rather than post diffs and discuss them, i should have started with the
> discussion.  I'll try that now.  I think logically, the changes i'd like
> to see can be broken down in small pieces:
> 
> 1 -- Expand "other files for which changes should be logged" to say
>      explicitly "media files" instead of "help files".
> 
>      Rationale: (a) increasing relevance of media files for certain
>      program classes; (b) better (more orthogonal) "coverage", since
>      "help files" and "manuals" overlap conceptually; (c) see point 3.
>
> 2 -- Clarify "change log entry", making a distinction between a "change
>      set" (introducing this term) and an "individual change".  A single
>      change log entry corresponds to a change set, which comprises one
>      or more individual changes.  Leave granularity of "individual
>      change" (file, func, form) open to interpretation.
> 
>      Rationale: Although people can infer "batch of changes" to mean
>      "change set", the latter is current and it's better to be explicit.
>      Separating "change log entry" from "individual change" and instead
>      associating it with "change set" makes it easier to refer to later
>      (see point 5, below).
>
+0

I have no strong feelings on these, so I won't comment, and I'll agree with
the decisions the other people here will make.

 > 3 -- (dependent on points 1 and 2) Endorse the changelog as the *best*
>      place for rationale/why information for:
> 
>      - files that don't support comment syntax (e.g., media files);
> 
>      - a large change set, where something like:
> 
>          /* We need this for func 'foo', which used to be available
>             (conditionally) from "xyz.h" for system XYZ, but now
>             gnulib DTRT (unconditionally).  */
>          #include "header.h"
> 
>        in N files could benefit from factoring the N comments to a
>        single instance in the changelog.
> 
>      Rationale: We currently urge rationale/why information to be placed
>      in the comments, and that should not change.  This change maintains
>      that spirit, giving guidance for cases when "comments in code" is
>      impossible or unwieldy.
>
IMHO, this misses the most important scenario where comments in a ChangeLog
entries are justified (I'd say required): explaining the *why* of a *change*.
See my lengthy explanations in:

  <http://lists.gnu.org/archive/html/bug-standards/2012-05/msg00000.html>
  <http://lists.gnu.org/archive/html/bug-standards/2012-05/msg00009.html>

the main point that can be condensed from there being:

  The how and why the code works the way it works -- yes, that must
  definitely must go in code comments (albeit in most cases, placing
  also an "abridged" version in the commit message as well won't hurt).
  But the rationale of why a change is needed, and how it relates to
  previous changes or attempts -- that must go in the commit messages
  (albeit in some cases, reporting part of that history in code comments
  can be of great help).

> 4 -- Suggest TITLE (aka DESCRIPTION LINE) format; keep it optional.
> 
>      Rationale: This documents current practice.
>
And makes life easier for people syncing ChangeLog entries with VCS
commit messages, since prominent version control systems (like git)
handles the first line of a commit somewhat specially (expecting it
to be a summary line).

>      Originally, i had
>      wanted TITLE to be mandatory, but now i'm convinced that some
>      projects don't need it.
>
+0.5

I'm still not convinced that lacking a summary line is ever a good idea,
but I've agreed that recommending the summary line instead of mandating
it is still a good compromise.  So let's got for it.

> 5 -- (in line with 3, dependent on 4) Encourage "moderate" reference
>      information, in the form of previous change log entries, bug id
>      URIs, etc, in a standardized format.  Likewise w/ credits (e.g.,
>      "Reported by"), taking care to emphasize THANKS and AUTHORS as
>      authoritative.  Give some privacy guidelines while we're at it.
> 
>      Rationale: This documents current practice, including explicit
>      support by tools such as Emacs.  Also, THANKS is currently not
>      mentioned in {maintain,standards}.texi.  A little redundancy here
>      is a small price for increased community spirit.
>
+1

> Overall, the thrust is to edge ChangeLog files outward from strictly
> "what changed" ever so slightly towards "what changed and why", in the
> process making it easier to *follow* a chain of "what changed".  I think
> this is useful because jumping inside another's mind is not easy at all!
> This is doubly difficult when there are multiple jumps required.
> 
> Anyway, now i'll submit the above pieces in new threads, starting w/ 0
> and waiting to conclude one before starting another -- Karl: is that the
> best way?  One important point previously discussed but omitted above is
> addition of examples.  Those will accompany the patches.
>

Thanks for all your work on this,
  Stefano