Re: changelog format

[Thien-Thi Nguyen]

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

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.

4 -- Suggest TITLE (aka DESCRIPTION LINE) format; keep it optional.

     Rationale: This documents current practice.  Originally, i had
     wanted TITLE to be mandatory, but now i'm convinced that some
     projects don't need 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.

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.