changelog format

[Alfred M. Szmidt]

Is anyone still working on adding the ChangeLog description field?

[Thien-Thi Nguyen-6]

() ams@... (Alfred M. Szmidt)
() Sun, 26 Feb 2012 10:40:17 -0500

   Is anyone still working on adding the ChangeLog description field?

I suppose that would be me.  I will swap-in context, review the
discussion, and post a new patch for review in the next few days.

[Thien-Thi Nguyen-6]

() ams@... (Alfred M. Szmidt)
() Tue, 17 Jan 2012 14:44:05 -0500

      - There's no need to describe the full purpose of the
      [...]
      - function definition to explain what it does.

   Why is this section removed?

Because it mixes concepts and style (the "however, sometimes
... batch of changes"), and because the advice on writing comments
is no longer fully applicable (to non-software files, mentioned
first in the following paragraph).  Such advice is now an
"implementation detail", dependent on the kind of change to be
logged.

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

OK.

   Making the description line (title is confusing)

To me, "title" suggests succinctness and overall applicability,
and is itself succinct.  What would you suggest instead?

   mandatory is bad.  Many changes don't require it.

I'm ambivalent, but only because i still use RCS, for which it
does seem overkill to require TITLE (though, i have developed a
habit of including one, anyway).  I expect those who use a VCS w/
proper change-set (multiple files) model would not find such a
requirement onerous.  Rather, it's common contemporary practice.

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

This paragraph covers non-text formats as well, such as image
files (e.g., converting a set of PNGs to remove alpha channel).
Such changes might indeed be uncommon, but they do happen.  I've
changed an initial blurb to mention this (saying "media files"
instead of "help files").

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

OK, good idea.  The text now reminds the reader that link
permanence is an important criteria.

   Personally I am not fond of citing the mailing list thread,
   such information should be distilled and put into comments, or
   documentation.

Personally, i'm not fond of long URLs.

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

Yes.  Well, maybe.  After re-reading, i see that "entry"
traditionally refers to a single change in a file, that is the
part that starts with asterisk.

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

   I don't think ChangeLog shouldn't be used to give credit, that
   is what AUTHORS and then THANKS files are used for; see the
   GNU Maintainer Guide for details.  Or atleast, it shouldn't be
   encouraged as the place for saying thank you.

I agree, somewhat.  I included this item mostly as a nod to
existing practice (and font-lock support in Emacs).  Perhaps we
can de-emphasize it here, and/or link to the maintainer guide.
... Hmm, i see maintain.texi does not mention THANKS.

        followed by descriptions of specific changes.  (These examples are
      ! drawn from Emacs and GCC.)

      --- 3561,3567 ----

        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.

Why?

      + (A patch should be handled as described above.)

   ")." over ".)" please :-)

I never realized there was this option.  I've side-stepped the issue by
removing that sentence.

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

Yes, that's better.

      + Likewise, what constitutes the title is up to you.  We note
      + here only that many projects use the form: @var{topic}[,
      + @var{topic}@dots{}]: @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.

It's no big deal for Emacs to support project-specific formatting,
so i'm inclined to leave it as-is.  Another point of contention we
sidestep through loose specification is how to end the title -- some
projects prescribe punctuation, some proscribe it, some don't care.

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

Maybe you mean "rest"?  Anyway, i agree.

   Nice job.

Thanks for the review.  Please find attached the latest patch.

[Thien-Thi Nguyen-6]

Oops, forgot the patch.  Here it is:


 doc/standards.texi |  121 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 files changed, 109 insertions(+), 12 deletions(-)

diff --git a/doc/standards.texi b/doc/standards.texi
index fc0761f..daba204 100644
--- a/doc/standards.texi
+++ b/doc/standards.texi
@@ -3511,6 +3511,7 @@ history of how the conflicting concepts arose and who they came from.
 * Simple Changes::
 * Conditional Changes::
 * Indicating the Part Changed::
+* Change Log Examples::
 @end menu

 @node Change Log Concepts
@@ -3532,26 +3533,55 @@ control system such as RCS or CVS.  This can be converted automatically
 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.
-
 In the past, we recommended not mentioning changes in non-software
-files (manuals, help files, etc.) in change logs.  However, we've been
+files (manuals, media files, etc.) in change logs.  However, we've been
 advised that it is a good idea to include them, for the sake of
 copyright records.

+A set of changes in the @file{ChangeLog} has, at the minimum, the form:
+
+@example
+ TITLE
+ * ENTRY
+@end example
+
 The easiest way to add an entry to @file{ChangeLog} is with the Emacs
 command @kbd{M-x add-change-log-entry}.  An entry should have an
 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.
+Before each group of related entries, you should add the @dfn{title},
+a one line description or summary of the change.
+Between the title and the entries proper, you may optionally include
+paragraphs to:
+
+@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 (e.g., image files)---the
+change log is the best place.
+
+@item reference to external resources
+This includes bug report IDs, URIs to related mailing list threads, etc.
+Remember to choose URIs that are permanently accessible.
+
+@item reference to another change
+This is useful when a change is a fix or continuation
+of a previous change.
+
+@item give credit
+It is courteous to acknowledge the help of others.
+Although such information may be available indirectly through
+a URI, including it in the change log fosters community spirit
+and makes it more self-contained.
+Note, however, that the primary place to give credit is
+the top-level @file{THANKS} file.
+@c FIXME: Mention THANKS in maintain.texi; xref it.
+@end table

 @node Style of Change Logs
 @subsection Style of Change Logs
@@ -3560,7 +3590,7 @@ Then describe the changes you made to that function or variable.
 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.)
+drawn from Emacs and GCC, from back when the title was optional.)

 @example
 1998-08-17  Richard Stallman  <rms@@gnu.org>
@@ -3625,6 +3655,28 @@ rather than this:

 As for the date, that should be the date you applied the change.

+In the paragraph(s), URIs should have angle braces and
+credits may optionally exclude the contributor's email address
+(to discourage spambots).
+
+A reference to another change should be expressed as a date
+and optionally a title if the date is insufficient to uniquely
+identify the reference.
+We recommend this over using a VCS commit identifier primarily
+to keep the change log self-contained, and secondarily to avoid
+lossage should the project switch to another VCS in the future.
+@c FIXME: Maybe a reference to gnu-vcs-fu is better.
+@c For generated change log files, you can use [gnu-vcs-fu ref] to [DTRT].
+
+Whether or not to add extra blank lines around the paragraph(s) 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}[, @var{topic}@dots{}]: @var{description}
+(both with and without trailing punctuation).
+
 @node Simple Changes
 @subsection Simple Changes

@@ -3734,6 +3786,51 @@ deals with @code{sh} commands:
 user-specified option string is empty.
 @end example

+@node Change Log Examples
+@subsection Change Log Examples
+
+Here are two slightly-edited examples from coreutils and Serveez,
+respectively.
+
+@c Use @verbatim to avoid ugly over-indentation w/ @example.
+@verbatim
[phone]  Jim Meyering  <meyering@...>
+
+        ls: be responsive to interrupts when color-listing large dirs
+
+        This change fixes coreutils bug#10243.
+        Reported by Arkadiusz Miskiewicz.
+
+        Starting with commit adc30a83 (2004-04-24), when using --color,
+        ls inhibited interrupts to avoid corrupting the state of an
+        output terminal.  However, for very large directories, that
+        inhibition rendered ls uninterruptible for too long,
+        including a potentially long period even before any output
+        is generated.
+
+        * src/ls.c: Two phases of processing are time-consuming
+        enough that they can provoke this: the readdir loop and the
+        printing loop.  The printing was supposed to be covered by
+        a call to process_signals in
+        (print_name_with_quoting): ... but that call was mistakenly
+        guarded by a condition that might be false for many or even
+        all files being processed.  Call process_signals
+        unconditionally.
+        (print_dir): Also call process_signals in the readdir loop.
+        * NEWS (Bug fixes): Mention it.
+
[phone]  Thien-Thi Nguyen  <ttn@...>
+
+        [build int] Fix bug: Move codec glue Automake conds later.
+
+        Regression introduced 2011-07-15, "Use
+        Automake conditionals to gate codec glue".
+        Reported by Mike Gran.
+
+        * configure.ac (WITH_ZLIB, WITH_BZLIB): Move into section
+        "write it out", which is after "checks for header files".
+@end verbatim
+

 @node Man Pages
 @section Man Pages

[Stefano Lattarini]

Hi Thien, thanks for not giving up on this.  Just a couple of minor
observations ...

On 04/28/2012 02:13 PM, Thien-Thi Nguyen wrote:

> () ams@... (Alfred M. Szmidt)
> () Tue, 17 Jan 2012 14:44:05 -0500
>
>       - There's no need to describe the full purpose of the
>       [...]
>       - function definition to explain what it does.
>
>    Why is this section removed?
>
> Because it mixes concepts and style (the "however, sometimes
> ... batch of changes"), and because the advice on writing comments
> is no longer fully applicable (to non-software files, mentioned
> first in the following paragraph).  Such advice is now an
> "implementation detail", dependent on the kind of change to be
> logged.
>
>       + 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.
>
> OK.
>
>    Making the description line (title is confusing)
>
> To me, "title" suggests succinctness and overall applicability,
> and is itself succinct.  What would you suggest instead?
>

"Summary" perhaps?

>    mandatory is bad.  Many changes don't require it.
>
> I'm ambivalent, but only because i still use RCS, for which it
> does seem overkill to require TITLE (though, i have developed a
> habit of including one, anyway).
>
And tomorrow you might convert your RCS repository to git, in which
case you'll indeed be grateful to this habit of yours ;-)

Thanks,
  Stefano

[Stefano Lattarini]

On 04/28/2012 02:15 PM, Thien-Thi Nguyen wrote:
> Oops, forgot the patch.  Here it is:
>
I really like your patch, it's a definte improvement over the
previous situation.  I strongly disagree on one point though:

  +A reference to another change should be expressed as a date
  +and optionally a title if the date is insufficient to uniquely
  +identify the reference.
  +We recommend this over using a VCS commit identifier primarily
  +to keep the change log self-contained, and secondarily to avoid
  +lossage should the project switch to another VCS in the future.

Here, we should advise to use the date and (optionally) the summary
of the referenced change *in addition* to its commit ID (or a
proper "abridged" versions thereof, e.g., in git, the output of
"git describe").  Otherwise, one loses the possibility of following
cross-references between commits with a single click of mouse when
browsing the VCS history through tools like 'gitk' (and the
equivalent ones for other VCS).

Thanks,
  Stefano

[Thien-Thi Nguyen-6]

() Stefano Lattarini <stefano.lattarini@...>
() Sat, 28 Apr 2012 19:22:14 +0200

   > To me, "title" suggests succinctness and overall applicability,
   > and is itself succinct.  What would you suggest instead?

   "Summary" perhaps?

To my ear, "summary" is almost like "abstract" (in the sense of a
scientific paper), which is not as succinct.

   > i still use RCS, for which it does seem overkill to require
   > TITLE (though, i have developed a habit of including one,
   > anyway).

   And tomorrow you might convert your RCS repository to git, in
   which case you'll indeed be grateful to this habit of yours ;-)

Very true.

[Thien-Thi Nguyen-6]

() Stefano Lattarini <stefano.lattarini@...>
() Sat, 28 Apr 2012 19:30:00 +0200

     +A reference to another change should be expressed as a date
     +and optionally a title if the date is insufficient to uniquely
     +identify the reference.
     +We recommend this over using a VCS commit identifier primarily
     +to keep the change log self-contained, and secondarily to avoid
     +lossage should the project switch to another VCS in the future.

   Here, we should advise to use the date and (optionally) the
   summary of the referenced change *in addition* to its commit ID
   (or a proper "abridged" versions thereof, e.g., in git, the
   output of "git describe").

I don't think the current wording precludes using a VCS commit ID,
additionally; "recommend over" doesn't prohibit such info.  Maybe
that's a personal quirk, though (i don't take myself or this
document as seriously as, say, "MUST NOT" in an RFC protocol spec).

   Otherwise, one loses the possibility of following
   cross-references between commits with a single click of mouse
   when browsing the VCS history through tools like 'gitk' (and
   the equivalent ones for other VCS).

Could you suggest another wording, then?

[Stefano Lattarini]

On 04/28/2012 07:53 PM, Thien-Thi Nguyen wrote:
>
> Could you suggest another wording, then?
>
What about this?

  A reference to another change should contain, in addition to its
  VCS commit identifier, its date, and optionally a title if the date
  is insufficient to uniquely identify the reference.  We recommend
  this over using exclusively a VCS commit identifier, primarily
  to keep the change log more self-contained, and secondarily to avoid
  lossage should the project switch to another VCS in the future.

Thanks,
  Stefano

[Karl Berry]

          + (A patch should be handled as described above.)
       ")." over ".)" please :-)

This small English point caught my eye.  When a parenthetical statement
really is a sentence, as is above, the period goes inside the parentheses.

  (A patch should be handled as described above).
would make no sense at all.

On the other hand, with a parenthetical non-sentence at the end of a
sentence, the period follows the parentheses, as if the parenthetical
was not there (like this).

I could go on, but anyway.

karl

[Alfred M. Szmidt]

      > To me, "title" suggests succinctness and overall applicability,
      > and is itself succinct.  What would you suggest instead?

      "Summary" perhaps?

   To my ear, "summary" is almost like "abstract" (in the sense of a
   scientific paper), which is not as succinct.

What about description line/field, since that is what it is; it
describes the entry.

[Alfred M. Szmidt]

I think you are trying to change a bit to much to quickly; the
"There's no need ..." paragraph contains useful information that was
removed.  Some small changes that I don't understand, why was help
files changed to media files?  And that you are trying to make the
description field mandatory is my biggest issue.

I'd always use real examples instead of `templateish' snippets; they
add the additional information of where to look for ChangeLog entries
in the real world.

I'll send a suggestion tomorrow...

[Stefano Lattarini]

[Quoting all the old message to keep context]
[Sorry for the awful delay]

On 01/21/2012 02:11 PM, Alfred M. Szmidt wrote:

>    >    >    --- 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.
>
>    Why not?  Many GNU projects either autogenerate the ChangeLog from the VCS
>    commit messages, or, even when using a version-controlled ChangeLog, keep
>    each of its entries in sync with the correspondent VCS commit message.  This
>    is not a fact that should ignored.  Good and meaningful recommendations have
>    to take existing practice into account.
>
> Some projects generate the ChangeLog file from commit messages, but
> not that many.  Please don't exaggerate.  Keeping the ChangeLog file
> in sync with the commit messages is hard, sometimes impossible since
> it requires rewriting history
>

How so?

> and you need to do special hacks for it (Jim Meyering has written one
> for git).
>
>    > Also, you are exgagerating, very few handle it specially.
>
>    Git does.  Mercurial does.  These alone are enough to steer a decision IMHO.
>    (I think Bazaar as well handles the summary line specially in some respects,
>    but I'm not sure about this).
>
> That is two, out of several dozen.  Neither CVS nor RCS handle this,
> BZR doesn't either.  I don't think darcs has anything special hacks
> for it.  Those are the ones I use on a daily basis other than git/bzr.
> I know that sccs doesn't handle it, nor does tla.
>
>    > 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,
>
>    This strikes me as wrong.  Don't you feel the need to explain why
>    you are renaming a function?  Even a simple summary line like:
>
>      refactor: rename func set_colours to set_colors (we prefer US spelling)
>
>    immediately makes clear to the reader what the change is about
>    *and* what its reasons are, without forcing it to read anything
>    else (either diffs of the body of the CL).
>
> Such comments should be in coding guide lines;
>

Even if they are already there, that is no excuse not to explain the reason
for the change in the commit message.  You would still need something like
this:

  refactor: rename func set_colours to set_colors

  As per our guidelines, we prefer US spelling in function and variable names.

  * foo.c, foo.h (set_colours): Renamed ...
  (set_colors): .. to this.
  * All callers: Adjusted accordingly.

Let me stress this, because it is an important point: the fact that a user
could theoretically work out the reason of a change by reading the coding
guidelines or the manual or whatever is *not* in any way a valid excuse
not to explain (or at least summarize) that reason in the commit message
as well.  When explaining things to a human being, "creative" repetition
and some redundancy are a good thing; we are not computers.

> I'd even go as for as
> suggest such an addition to the GCS that American spelling is prefered
> over British.  But I don't feel strongly about it enough.
>
My point wasn't about American vs. British spelling; I just used that
as an example.  We shouldn't get lost in this irrelevant tangent.

>    > 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 <gnu@...>
>    >
>    > * 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.
>
>    I strongly disagree.
>
>    First, I need to read *all* the ChangeLog entry to just understand what the
>    change is about.  Much worse, even then I can only *guess* at what the reason
>    behind this change is.
>
> What the change is about is not the purpose of ChangeLog; it describes
> how the code changed.  Not _why_!
>

Then the ChangeLog is mostly useless, and writing it mostly a waste of time.
I'm not the fist one to reach this conclusion:
  <http://gcc.gnu.org/ml/gcc/2007-12/msg00016.html>
  <http://thread.gmane.org/gmane.comp.gcc.devel/94464/>

>    In fact, in this particular case, by reading the above I can't even understand
>    what the change is supposed to do (let alone why it is needed).  Does this change
>    mean that you don't use any function/macro declared in the <malloc.h> header
>    anymore, so the checking for it and the use of it can go away?  Or does it mean
>    that you now unconditionally assume malloc() and friends to be declared in
>    <stdlib.h>, which your C files already include?  
>
> The entry states it clearly, ./configure no longer checks for
> <malloc.h>; and one doesn't include <malloc.h> in some source files.
> The _why_ of the change is for another place; i.e. in this case coding
> guidelines regarding pre-ANSI C systems.
>

This way, you loose the coupling between the change and the reason behind it.
A better thing to do would: update your coding guidelines, then do your commit
and write something like this in the the commit message:

  cleanup: stop checking for <malloc.h>

  As per our coding guidelines, we can now assume being compiled with a
  conforming ANSI C environmentm, where malloc is declared in <stdlib.h>

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

So, a user reading the commit message four years from now will immediately know
why the change was done, and if hew wants to know more details, he will simply
have a look at the (say) 'docs/CodingGuildelines.txt' file as it was in that
same commit.  Clear, efficient, and with no real repetition.  What's wrong with
this?

>    > 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).
>
>    And this is what Automake (of which I'm co-maintainer) does as well :-)
>
>    My point was only that, in case of URLs to a bug tracker entry, the problem
>    of URL breakage is greatly mitigated by the fact that those URLs are very
>    very likely to contain a reference to the bug ID (which should never break).
>
> Agreed about the bug ID being unique for each project, simply store
> those in the CL and somehow resolve the ID to a URL through other
> means.
>
>    > 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.
>
>    This might not be viable for a one-man project.  Especially if the lone
>    maintainer inherits an already-big project lacking such internal
>    documentation.
>
> Hacking up a simple INTERNALS whatever file is quite simple; I don't
> see the problem.
>
>    >   Stefano Lattarini: Added numerous test cases, ....
>    >
>    > This is more concise, and easier to look at.
>
>    And become unwieldy for users that have contributed with lots of
>    suggestions and bug reports.
>
> You can prune the line.
>
>    >    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."
>
>    (You haven't said anything about these, so I assume they are good
>    examples).
>
> Right, I don't use them my self though.
>
>    > Which makes it more prudent to make it optional; since everyone
>    > will have a differnt opinion on it.
>
>    But I'm convinced mine is not an opinion, but a *position*
>    motivated by sound technical arguments (see my previous answer for
>    them).  That's why I'm pushing so hard (and will continue to) to
>    make the summary line *unconditionally mandatory*.
>
> How about a compromise? Make it recommended, but not mandatory.  And
> leave it up to maintainers do decide how hard they wish to enforce the
> policy.
>

Well, I guess that would be better than the present situation where the
summary line is not even recommended.  So OK from me in this respect.

>    > The maintainer can decide if it should be mandatory or not for
>    > per project.
>
>    IMHO no, not anymore than he can decide whether his project should
>    have a GCS-conforming configure script or not.
>
> The comparison is not just, ./configure is for the users benefit.
> ChangeLog is for the maintainers and developers.
>

Regards,
  Stefano

[Ludovic Courtès-3]

Hi!

(Resending a message that Gmane had apparently swallowed.)

Stefano Lattarini <stefano.lattarini@...> skribis:

> Then the ChangeLog is mostly useless, and writing it mostly a waste of time.
> I'm not the fist one to reach this conclusion:
>   <http://gcc.gnu.org/ml/gcc/2007-12/msg00016.html>
>   <http://thread.gmane.org/gmane.comp.gcc.devel/94464/>

That’s the great misunderstanding about change logs.

What, to me, summarizes the rationale best is this paragraph (info
"(standards) Change Log Concepts"):

     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.

Indeed, it’s more convenient when the explanation is next to the code,
rather than buried in the VCS history.

And change logs serve a different purpose: they give a higher-level view
of the diff, sort-of like a semantic patch.

Thanks,
Ludo’.

[Stefano Lattarini]

Hello everybody.

On 12/22/2011 11:41 PM, Karl Berry wrote:

> Hi Stefano, Thien-Thi,
>
> I'm sorry, but I can't follow a thread of a bunch of messages or more
> started on another list (of a thread of hundreds of unrelated messages :),
> where each message has tons of quoted material followed by brief
> commentary and small changes.  Even if I tried to work my way through
> all the discussion, I would surely make a mistake.
>
> If the idea is still in "discussion mode" between you two, that's fine,
> feel free to keep cc-ing the list :).  But if you want me to actually
> understand, please send a proposed diff to standards.texi with the new
> words.  Or, if you don't have the new words yet, and just want a
> reaction to the ideas, please send a summary of what you want to change,
> without any quoting :), and maybe I can suggest something.
>

Is this thread still alive, or have we, again :-(, dropped the ball on this?
It seemed to me we were near to reach consensus on the latest patches posted
by Thien-Thi.  And it is a shame that the ChangeLog recommendations are so
out-of-sync with the current usages and best practices.

Regards,
  Stefano

[Thien-Thi Nguyen-6]

() Stefano Lattarini <stefano.lattarini@...>
() Wed, 23 May 2012 11:24:25 +0200

   Is this thread still alive, or have we, again :-(, dropped the
   ball on this?  It seemed to me we were near to reach consensus
   on the latest patches posted by Thien-Thi.  And it is a shame
   that the ChangeLog recommendations are so out-of-sync with the
   current usages and best practices.

It seems the main point of contention is whether or not TITLE
is mandatory.  If it's not mandatory, i see no point in making
the proposal -- status quo (everything optional) is fine.

The last i recall is that ams was going to post more comments.
(That's what i'm waiting for, at least.  Have i misunderstood?)

[Stefano Lattarini]

Hi Thien-Thi.

On 05/23/2012 12:22 PM, Thien-Thi Nguyen wrote:

> () Stefano Lattarini <stefano.lattarini@...>
> () Wed, 23 May 2012 11:24:25 +0200
>
>    Is this thread still alive, or have we, again :-(, dropped the
>    ball on this?  It seemed to me we were near to reach consensus
>    on the latest patches posted by Thien-Thi.  And it is a shame
>    that the ChangeLog recommendations are so out-of-sync with the
>    current usages and best practices.
>
> It seems the main point of contention is whether or not TITLE
> is mandatory.
>

We agreed it should be recommended, rather than strictly mandatory:
<http://lists.gnu.org/archive/html/bug-standards/2012-05/msg00000.html>
(which is a good step forward IMHO).

> If it's not mandatory, i see no point in making
> the proposal -- status quo (everything optional) is fine.
>
I seem to recall you had made several other improvements as well, in
addition to the summary line; am I mistaken?  At this point, could you
please post again the latest version of your proposed patch, for a
fresh round of reviews?

> The last i recall is that ams was going to post more comments.
> (That's what i'm waiting for, at least.  Have i misunderstood?)
>
I don't know, sorry; I've lost track who's waiting who here (for all
I remember, you might have been waiting comments from me :-)

Thanks for your perseverance,
  Stefano

[Stefano Lattarini]

On 05/02/2012 11:52 PM, Ludovic Courtès wrote:
> Hi!
>
Hi Ludo.

> (Resending a message that Gmane had apparently swallowed.)
>
> Stefano Lattarini <stefano.lattarini@...> skribis:
>
>> Then the ChangeLog is mostly useless, and writing it mostly a waste of time.
>> I'm not the fist one to reach this conclusion:
>>   <http://gcc.gnu.org/ml/gcc/2007-12/msg00016.html>
>>   <http://thread.gmane.org/gmane.comp.gcc.devel/94464/>
>
> That’s the great misunderstanding about change logs.
>

I think there's no misunderstanding on my part.  I understand what the GNU
Coding standards recommend about the ChangeLogs; I just believe those
recommendations are outdated if not downright wrong, and should be fixed.

> What, to me, summarizes the rationale best is this paragraph (info
> "(standards) Change Log Concepts"):
>
>      There's no need to describe the full purpose of the changes or how
>   they work together.
>
Which, followed to the letter, would make the ChangeLog entries basically
worthless for all but the most trivial commits.

>   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.
>
> Indeed, it’s more convenient when the explanation is next to the code,
>

It depends.  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 placed in the commit message 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).

> rather than buried in the VCS history.
>
The two approaches are not mutually exclusive, but complementary: some
comments goes in the VCS history, some in the code/documentation, and
some in both places.

> And change logs serve a different purpose: they give a higher-level view
> of the diff, sort-of like a semantic patch.
>
This is a good aspect, but it complements rather than substitute the
higher-level explanation and motivation of a change.  Let me take a
recent Automake-NG commit as an example:

    [ng] config.h.{bot,top}: don't support anymore (distribution and deps)

    The use of those files have been obsoleted since Autoconf commit 5047ea80
    of 1994-08-09, "support alternate input file names"; yes, the "1994" in
    there is not a typo: those files were already deprecated in Autoconf 2.0.
    It's well past time to remove support for them!

    For more information, see chapter "Obsolete Constructs", section
    "acconfig.h" of the Autoconf manual.  See also the discussion on automake
    bug#7919, in particular the message <http://debbugs.gnu.org/7819#20>.

    * NG-NEWS: Update.
    * automake.in (handle_configure): Don't automatically distribute the
    'config.h.top' and 'config.h.bot' files if they exist, and don't add
    them to the '%FILES%' transform when processing the 'remake-hdr.am'
    Makefile fragment.  In fact, drop the '%FILES%' transform altogether,
    since now it would always expand to empty.
    (@common_sometimes): Don't list 'config.h.top' and 'config.h.bot'
    anymore.
    * lib/am/remake-hdr.am (%CONFIG_HIN%): Don't depend on '%FILES%'
    anymore.  That transform has been removed now (and wouldn't be needed
    anyway).
    * t/autodist-config-headers.sh: Remove as obsolete.

and examine it in detail.

SUMMARY LINE

    [ng] config.h.{bot,top}: don't support anymore (distribution and deps)

This says in a line what the commit does.  it is useful for people skimming
the VCS history (to quickly determine if the commit is relevant to them);
this is especially true for GUI/WEB tools like gitweb and gitk, which
present an overview of the history where only the summary lines are visible.

MOTIVATION AND REFERENCES

    The use of those files have been obsoleted since Autoconf commit 5047ea80
    of 1994-08-09, "support alternate input file names"; yes, the "1994" in
    there is not a typo: those files were already deprecated in Autoconf 2.0.
    It's well past time to remove support for them!

    For more information, see chapter "Obsolete Constructs", section
    "acconfig.h" of the Autoconf manual.  See also the discussion on automake
    bug#7919, in particular the message <http://debbugs.gnu.org/7819#20>.

This explains why the changes done by the commit are a good move, rather
than simple "code churn", giving detailed references.  If someone in the
future question the usefulness or goodness of the commit ("why have you
broken backward compatibility for such a small code simplification?") we
can answer him with rationale ("that was compatibility for an usage
deprecated by eighteen years").

DETAILED PER-FILE CHANGES

    * NG-NEWS: Update.

This is just noise, but is mandated by the GCS, and since consistency
is good, I'd rather have it than not.

    * automake.in (handle_configure): Don't automatically distribute the
    'config.h.top' and 'config.h.bot' files if they exist, and don't add
    them to the '%FILES%' transform when processing the 'remake-hdr.am'
    Makefile fragment.  In fact, drop the '%FILES%' transform altogether,
    since now it would always expand to empty.
    (@common_sometimes): Don't list 'config.h.top' and 'config.h.bot'
    anymore.
    * lib/am/remake-hdr.am (%CONFIG_HIN%): Don't depend on '%FILES%'
    anymore.  That transform has been removed now (and wouldn't be needed
    anyway).
    * t/autodist-config-headers.sh: Remove as obsolete.

This has the role of "semantic patch" you was referring to.  Don't just
report the single diffs (which already present in the "git diff" output
anyway), but explain why they are needed / makes sense.  True, there is
some duplication with what "git diff" would tell us anyway, that that's
acceptable (and as I've already stated in a previous message, having
some redundancy when explaining things to a human usually makes more
good than harm).

Regards,
  Stefano

[Karl Berry]

As I warned from the beginning, I haven't been trying to follow the
details of the proposal you're working out.

However, I want to warn you that sending rms a huge patch changing
everything with a zillion-line rationale is not going to get anywhere
with rms.  From the latest descriptions, I fear that is where you are.

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

k

[Thien-Thi Nguyen-6]

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