Re: changelog format

[Thien-Thi Nguyen]

() Stefano Lattarini <address@hidden>
() Thu, 24 May 2012 11:30:15 +0200

   > 3 -- (dependent on points 1 and 2) Endorse the changelog as the *best*
   >      place for rationale/why information for: [...]

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

I don't agree that it's required (since the overall thrust is to edge
ever so slightly; the "and why" is not universally highly valued).
Thus, i considered this rationale to be weaker than the others for this
particular spate of changes (that is, whereas the other reasons describe
clear(er) need, this one describes good practice).

That said, given ‘s/must/could/3’ and slight reworking, i think that
paragraph would be a good candidate for the intro blurb, once we finish
this (conservative, remember "ever so slightly") round.  (Translation:
I sympathize but wish to focus scope, to ratchet results and move on.)

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

Right.

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

FWIW, i agree personally, but adopt a separate pov for the task at hand.

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

Note that i do mention "and why".