changelog format

[Karl Berry]

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.

Thanks,
karl

[Thien-Thi Nguyen-6]

() karl@... (Karl Berry)
() Thu, 22 Dec 2011 14:41:37 -0800

   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.

Yeah, we're still hashing this out.  This will go on for a couple more
messages, probably.  I will then follow-up to this thread w/ a proper patch
(w/ introductory blurb, against the version in gnulib), for the next cycle.
Hopefully this way we don't take too much of your time.

Would you prefer we do the hashing off-list?  I suppose i should have asked
at the start -- sorry about that.

[Karl Berry]

    Would you prefer we do the hashing off-list?  I suppose i should have asked
    at the start -- sorry about that.

No problem.  I don't mind either way, as long as I'm not expected to
follow it until something comprehensible comes across my screen :).

I don't know if any of the (few) other people on bug-standards are
interested, but in any case, if you want a (public :) archive of the
thread, feel free to keep cc-ing the list.

best,
karl

[Thien-Thi Nguyen-6]

() karl@... (Karl Berry)
() Fri, 23 Dec 2011 15:47:40 -0800

   I don't know if any of the (few) other people on bug-standards are
   interested, but in any case, if you want a (public :) archive of the
   thread, feel free to keep cc-ing the list.

OK.  Please find below a proposed patch to standards.texi.

___________________________________________________________________

*** 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.
-
  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:
+
+ @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.
+
+ @item link to external resources
+ This includes bug report or mailing list URLs.
+
+ @item link to another entry
+ 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 URL, including it
+ in the change log fosters community spirit and makes it more
+ self-contained.
+ @end table
 
  @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.)
 
  @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.)  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
+ 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}[, @var{topic}@dots{}]: @var{description}.
+
+ Here is a slightly-edited example from the Serveez top-level ChangeLog:
+
+ @example
+ 2011-10-26  Thien-Thi Nguyen  <ttn@@gnuvola.org>
+
+         [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 example
+
  @node Simple Changes
  @subsection Simple Changes
 

[Stefano Lattarini]

Hi Thien-Thi, thanks for having worked on this!  I like you proposal very
much, with only a couple of nits nit (find them below).

On 01/17/2012 12:26 PM, Thien-Thi Nguyen wrote:

> () karl@... (Karl Berry)
> () Fri, 23 Dec 2011 15:47:40 -0800
>
>    I don't know if any of the (few) other people on bug-standards are
>    interested, but in any case, if you want a (public :) archive of the
>    thread, feel free to keep cc-ing the list.
>
> OK.  Please find below a proposed patch to standards.texi.
>
> ___________________________________________________________________
>

> 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
> over using a version control system commit identifier
>
I'd really, really like to see "in addition to" instead of "over"
used her, since VCS commit identifiers have at least an important
advantage of their own: they make it immediate for the reader to
refer to the linked entry, instead of having to rely on (say)
"git log --grep" or "git log --since=... --until=...".  This is
even more true for GUI interfaces to the VCS, where VCS commit
identifiers might be automatically turned in clickable links.

> Here is a slightly-edited example from the Serveez top-level ChangeLog:
>
[SNIP]

I think it would be nice to also ad another example with a slightly
different style.  I propose this slightly edited version of the commit
message for the GNU coreutils commit 'c592a00f':

    ls: be responsive to interrupts when color-listing large directories

    This change fixes coreutils bug#10243.

    Starting with commit adc30a83, 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.

    Report by Arkadiusz Miskiewicz.

Thanks,
  Stefano

[Thien-Thi Nguyen-6]

() Stefano Lattarini <stefano.lattarini@...>
() Tue, 17 Jan 2012 13:09:34 +0100

   thanks for having worked on this!  I like you proposal very
   much, with only a couple of nits nit (find them below).

I appreciate your patience.

   > A link to another entry [...].  We recommend this
   > over using a version control system commit identifier
   >
   I'd really, really like to see "in addition to" instead of "over"
   used her, since VCS commit identifiers have at least an important
   advantage of their own: they make it immediate for the reader to
   refer to the linked entry, instead of having to rely on (say)
   "git log --grep" or "git log --since=... --until=...".  This is
   even more true for GUI interfaces to the VCS, where VCS commit
   identifiers might be automatically turned in clickable links.

I agree that such conveniences are very compelling.  My fear
is that people would use VCS commit identifiers exclusively;
saying "in addition to" is not strong enough.  Any other ideas?

   I think it would be nice to also ad another example with a slightly
   different style.  I propose this slightly edited version of the commit
   message for the GNU coreutils commit 'c592a00f': [...]

Good idea.  What is the ChangeLog header for this?  Can i assume:
  2011-12-08  Jim Meyering  <meyering@...>
as per ‘git show c592a00f’?  (Meta-comment: This extra step shows
how generated ChangeLog files are inconvenient to casual readers.)

I note that there is more than one paragraph, so i guess i'll change
the "short paragraph" to "paragraph(s)".

[Thien-Thi Nguyen-6]

() Stefano Lattarini <stefano.lattarini@...>
() Tue, 17 Jan 2012 13:09:34 +0100

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

       Report by Arkadiusz Miskiewicz.

I just noticed: The Report line is below the usual mass of
contiguous *-entries.  Shouldn't it be above?  (Either that, or
"part of" the mass, i.e., part of a specific *-entry.)

[Stefano Lattarini]

On 01/17/2012 02:43 PM, Thien-Thi Nguyen wrote:

> () Stefano Lattarini <stefano.lattarini@...>
> () Tue, 17 Jan 2012 13:09:34 +0100
>
>        * 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.
>
>        Report by Arkadiusz Miskiewicz.
>
> I just noticed: The Report line is below the usual mass of
> contiguous *-entries.  Shouldn't it be above?  (Either that, or
> "part of" the mass, i.e., part of a specific *-entry.)
>

It's fine by me to move the "Reported by" line above the "*-entries mass".
In my previous message, it appeared below simply because it does so in the
original, "real" commit log message I took as a source; but that doesn't
mean we can't tweak that in our example, to make it more conforming to the
new "best practices".

Thanks,
  Stefano

[Stefano Lattarini]

On 01/17/2012 02:32 PM, Thien-Thi Nguyen wrote:
> () Stefano Lattarini <stefano.lattarini@...>
> () Tue, 17 Jan 2012 13:09:34 +0100
>
>    thanks for having worked on this!  I like you proposal very
>    much, with only a couple of nits nit (find them below).
>
> I appreciate your patience.
>
I appreciate your work :-)

>    > A link to another entry [...].  We recommend this
>    > over using a version control system commit identifier
>    >
>    I'd really, really like to see "in addition to" instead of "over"
>    used her, since VCS commit identifiers have at least an important
>    advantage of their own: they make it immediate for the reader to
>    refer to the linked entry, instead of having to rely on (say)
>    "git log --grep" or "git log --since=... --until=...".  This is
>    even more true for GUI interfaces to the VCS, where VCS commit
>    identifiers might be automatically turned in clickable links.
>
> I agree that such conveniences are very compelling.  My fear
> is that people would use VCS commit identifiers exclusively;
>

Honestly I've been guilty of doing so for quite a long time now (and should
get rid of this bad habit ASAP).  But my (or others?) laziness/sloppiness is
IMHO no excuse to give in incorrect advice in the GCS.

> saying "in addition to" is not strong enough.  Any other ideas?
>
Maybe we could provide a "blessed" script that the developer could use in lieu
of "git describe" (or similar commands for other VCS) to get a GCS-conforming
string referring to a past commit.  The idea is that, instead of doing something
like this:

  $ git describe c592a00f
  v8.14-91-gc592a00

the developer could do something like this:

  $ gnu-vcs-describe c592a00f
  v8.14-91-c592a00 (2011-12-08, "ls: be responsive to interrupts ...")

WDYT?

>    I think it would be nice to also ad another example with a slightly
>    different style.  I propose this slightly edited version of the commit
>    message for the GNU coreutils commit 'c592a00f': [...]
>
> Good idea.  What is the ChangeLog header for this?  Can i assume:
>   2011-12-08  Jim Meyering  <meyering@...>
> as per ‘git show c592a00f’?
>
Yes.

> (Meta-comment: This extra step shows
> how generated ChangeLog files are inconvenient to casual readers.)
>
How so?  Note that I've copied & pasted the above from the git output, not
from the corresponding generated ChangeLog.

> I note that there is more than one paragraph, so i guess i'll change
> the "short paragraph" to "paragraph(s)".
>
+1

Thanks,
  Stefano

[Thien-Thi Nguyen-6]

() Stefano Lattarini <stefano.lattarini@...>
() Tue, 17 Jan 2012 15:05:54 +0100

   > I agree that such conveniences are very compelling.  My fear
   > is that people would use VCS commit identifiers exclusively;

   Honestly I've been guilty of doing so for quite a long time now (and should
   get rid of this bad habit ASAP).  But my (or others?) laziness/sloppiness is
   IMHO no excuse to give in incorrect advice in the GCS.

   > saying "in addition to" is not strong enough.  Any other ideas?
   >
   Maybe we could provide a "blessed" script that the developer could use in lieu
   of "git describe" (or similar commands for other VCS) to get a GCS-conforming
   string referring to a past commit.  The idea is that, instead of doing something
   like this:

     $ git describe c592a00f
     v8.14-91-gc592a00

   the developer could do something like this:

     $ gnu-vcs-describe c592a00f
     v8.14-91-c592a00 (2011-12-08, "ls: be responsive to interrupts ...")

   WDYT?

Sounds fine, but i don't really want to think about implementation
details, especially Git-specific ones, though undoubtedly i would/will
benefit from them.  (Though i hugely favor Git personally, i like RCS,
too, and am trying to do this standards.texi munging w/ a VCS-agnostic
mindset.)

Anyway, i've reworded that part a bit, leaving a placeholder for
gnu-vcs-fu (but commented out).  We can address this later, no?

   >   2011-12-08  Jim Meyering  <meyering@...>

   Yes.

OK, thanks for confirming.

   > (Meta-comment: This extra step shows
   > how generated ChangeLog files are inconvenient to casual readers.)

   How so?  Note that I've copied & pasted the above from the git
   output, not from the corresponding generated ChangeLog.

Well, i didn't have coreutils repo (or tarballs) locally, so i had to
clone it and do "git log", to find that information.

   > I note that there is more than one paragraph, so i guess i'll change
   > the "short paragraph" to "paragraph(s)".
   >
   +1

OK.  Attached is the latest diff.  In addition to the above changes, i
moved the examples to their own node, refilling the one from coreutils
slightly.  I also used @verbatim, but am not sure if that's cool or not.

________________________________________________

*** a/doc/standards.texi
--- b/doc/standards.texi
***************
*** 3,9 ****
  @setfilename standards.info
  @settitle GNU Coding Standards
  @c This date is automagically updated when you save this file:
! @set lastupdate December 10, 2011
  @c %**end of header

  @dircategory GNU organization
--- 3,9 ----
  @setfilename standards.info
  @settitle GNU Coding Standards
  @c This date is automagically updated when you save this file:
! @set lastupdate gennaio 17, 2012
  @c %**end of header

  @dircategory GNU organization
***************
*** 3495,3500 ****
--- 3495,3501 ----
  * Simple Changes::
  * Conditional Changes::
  * Indicating the Part Changed::
+ * Change Log Examples::
  @end menu

  @node Change Log Concepts
***************
*** 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.
-
  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
--- 3517,3522 ----
***************
*** 3536,3541 ****
--- 3527,3559 ----
  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 zero or more
+ 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---the change log is the
+ best place.
+
+ @item link to external resources
+ This includes bug report or mailing list URLs.
+
+ @item link to another entry
+ 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 URL, including it
+ in the change log fosters community spirit and makes it more
+ self-contained.
+ @end table

  @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>
--- 3562,3568 ----
  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.)

  @example
  1998-08-17  Richard Stallman  <rms@@gnu.org>
***************
*** 3609,3614 ****
--- 3627,3653 ----

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

+ In the paragraph(s), 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.)
+
+ A link to another entry should be expressed as a date and an
+ optional title, if the date is insufficient to uniquely identify
+ a particular change.  We recommend this over using @strong{only}
+ a VCS commit identifier primarily to keep the change log
+ self-contained, and secondarily to avoid lossage should the
+ project change 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}.
+
  @node Simple Changes
  @subsection Simple Changes

***************
*** 3698,3703 ****
--- 3737,3787 ----
  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
+ 2011-12-08  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, 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.
+
+ 2011-10-26  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]

On 01/17/2012 05:04 PM, Thien-Thi Nguyen wrote:

>
> [SNIP]
>
>    > (Meta-comment: This extra step shows
>    > how generated ChangeLog files are inconvenient to casual readers.)
>
>    How so?  Note that I've copied & pasted the above from the git
>    output, not from the corresponding generated ChangeLog.
>
> Well, i didn't have coreutils repo (or tarballs) locally, so i had to
> clone it and do "git log", to find that information.
>

Oh, sorry.  But again, that's due to my sloppiness, not to the fact that
the ChangeLog is auto-generated.

>    > I note that there is more than one paragraph, so i guess i'll change
>    > the "short paragraph" to "paragraph(s)".
>    >
>    +1
>
> OK.  Attached is the latest diff.  In addition to the above changes, i
> moved the examples to their own node, refilling the one from coreutils
> slightly.  I also used @verbatim, but am not sure if that's cool or not.
>
>

Now that I've re-read the coreutils entry, I've noticed ...

> Starting with commit adc30a83, when using --color, ls
>
.. that we go against our own advice here, as we report only the VCS id
of the commit we are referring to.  So, what about this tweak?

  Starting with commit adc30a83 (2004-04-24), when using --color, ls

For the rest, the patch looks good.  Thanks again for tackling this!

Regards,
  Stefano

[Alfred M. Szmidt]

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

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

   + @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.  Personally I am not fond of
citing the mailing list thread, such information should be distilled
and put into comments, or documentation.

   + @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; see the GNU Maintainer
Guide for details.  Or atleast, 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.

     @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}[, @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.

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

Nice job.

[Alfred M. Szmidt]

Please wait with posting diffs 2-3 days, so one can hash out things.
It makes it hard to reply to one email, and then you see a new diff
without knowing what exactly changed.  Not everyone is connected 24/7
to the interwebs.

[Thien-Thi Nguyen-6]

() Stefano Lattarini <stefano.lattarini@...>
() Tue, 17 Jan 2012 17:38:32 +0100

   Oh, sorry.  But again, that's due to my sloppiness,
   not to the fact that the ChangeLog is auto-generated.

OK, no worries.

   Now that I've re-read the coreutils entry, I've noticed ...

   > Starting with commit adc30a83, when using --color, ls

   .. that we go against our own advice here, as we report only the VCS id
   of the commit we are referring to.

Good catch.

   So, what about this tweak?

     Starting with commit adc30a83 (2004-04-24), when using --color, ls

   For the rest, the patch looks good.  Thanks again for tackling this!

I have added that.  Latest diff follows.

____________________________________________________________

*** a/doc/standards.texi
--- b/doc/standards.texi
***************
*** 3495,3500 ****
--- 3495,3501 ----
  * Simple Changes::
  * Conditional Changes::
  * Indicating the Part Changed::
+ * Change Log Examples::
  @end menu

  @node Change Log Concepts
***************
*** 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.
-
  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
--- 3517,3522 ----
***************
*** 3536,3541 ****
--- 3527,3559 ----
  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 zero or more
+ 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---the change log is the
+ best place.
+
+ @item link to external resources
+ This includes bug report or mailing list URLs.
+
+ @item link to another entry
+ 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 URL, including it
+ in the change log fosters community spirit and makes it more
+ self-contained.
+ @end table

  @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>
--- 3562,3568 ----
  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.)

  @example
  1998-08-17  Richard Stallman  <rms@@gnu.org>
***************
*** 3609,3614 ****
--- 3627,3654 ----

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

+ In the paragraph(s), 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.)
+
+ A link to another entry should be expressed as a date and an
+ optional title, if the date is insufficient to uniquely identify
+ a particular change.  We recommend this over using @strong{only}
+ 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

***************
*** 3698,3703 ****
--- 3738,3788 ----
  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
+ 2011-12-08  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.
+
+ 2011-10-26  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

[Thien-Thi Nguyen-6]

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

   Please wait with posting diffs 2-3 days, so one can hash out
   things.  It makes it hard to reply to one email, and then you
   see a new diff without knowing what exactly changed.  Not
   everyone is connected 24/7 to the interwebs.

Sorry, i mistakenly assumed that no one was listening in.  I posted
the latest diff a few minutes ago (before seeing your message), as
part of a series of exchanges with Stefano Lattarini that is just
about finished.  Hopefully those messages will arrive to you sooner
than later, but in any case, i will wait a few days as you suggest
before continuing.

[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}[, @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.
>

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

[Alfred M. Szmidt]

   >    --- 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.  Also, you are exgagerating, very few handle it specially.  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, 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.

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

I find the "many files or changes to files that do not support a
comment syntax" to be redundant, if you have a file format that cannot
handle comments, it is easy to work around it, allowing for better
documentation of the program.  Simply say "For other circumstances the
change log is the best place.".

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

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

(bug#10260) is clickable, and the way to reference the bug report
stored in .dir-locals.el.  There is also already precedence for this;
emacs, gcc, gdb, binutils, coreutils.  Inventing, or changing how
things are done is hard, specially if they are for the worse.

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

Maybe we can suggest that one should prefer commenting over using a
URL then.  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.

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

You can do similar in THANKS.

  Stefano Lattarini: Added numerous tast cases, ....

This is more consice, and easier to look at.

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

Since this was an actual patch, this should be part of the CL header,
not as a note, like so (if it isn't copyright significant):

2111-11-11  Zack Weinberg  <...> (tiny change)

And if it is, and you had to rewrite it, then the format could (I'd
write would, but I realised only some projects do this) be:

2111-11-11  Zack Weinberg  <...>
            Stefano Lattarini <...>

Or some such.  The CL header should state who _wrote_ the change; not
who commited it.  Thus there is no need to mention a thank you for
patches, or suggestions since this information is already handled
elsewhere.

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

Which makes it more prudent to make it optional; since everyone will
have a differnt opinion on it.  The maintainer can decide if it should
be mandatory or not for per project.

[Stefano Lattarini]

On 01/17/2012 10:16 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.

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

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

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?  Are you just dropping an hack
for an obsolete system?  I can't say by reading that CL.  Something as simple as
this would have solved all these doubts and potential misunderstandings:

  Unconditionally assume malloc and friends are declared in <stdlib.h>

  That now holds for every non-museum system.  So stop checking for the <malloc.h>
  header, as well as including it: this compatibility workaround is no more needed.

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

>    >    + @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.
>
> I find the "many files or changes to files that do not support a
> comment syntax" to be redundant, if you have a file format that cannot
> handle comments, it is easy to work around it, allowing for better
> documentation of the program.
>

Ah, ok then.

(Still, maybe it would be worth explicitly stating that if you have a deep
change that touches several files in an intricate or non-obvious way, you
might not be able to explain the reason behind this change or the new
behaviour it implements in code comments scattered among some or even all
of those files -- you must do so in the CL instead.  But this can be left
for a later discussion).

> Simply say "For other circumstances the change log is the best place.".
>
I agree that for this first round this is good enough.  Improvements and
expansions can be done in a follow up patch (if we'll feel the need for
them).

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

> (bug#10260) is clickable, and the way to reference the bug report
> stored in .dir-locals.el.  There is also already precedence for this;
> emacs, gcc, gdb, binutils, coreutils.  Inventing, or changing how
> things are done is hard, specially if they are for the worse.
>
Fair enough.  If you want to propose a further enhancement preaching
against the dangers of using URLs instead of IDs to refer to bug reports,
I will happily praise it and back it up :-)

>    > 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.
>
> Maybe we can suggest that one should prefer commenting over using a
> URL then.
>

I'd heartily agree *if the these two things were mutually exclusive*.
But they are not: you can distillate a good rationale and put in the
comments and/or in the ChangeLog entry, *and also* add a symlink to
the original discussion at the same time.  Another example from the
Automake ChangeLog:

    progs, libs: implement EXTRA_foo_DEPENDENCIES

    Backported from commit `v1.11-377-g6edafbb'.

    The feature implemented by that change is quite unobtrusive, so
    adding it to a maintenance release is acceptable.  Also, there
    have been requests from real-world users for this feature since
    it has been implemented in master; see automake bug#9320:
     <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=9320>
    and this short discussion on the automake list:
     <http://lists.gnu.org/archive/html/automake/2010-11/msg00099.html>
    It would be a pity to make such users wait even more (until
    Automake 1.12 is out) before they could start using this feature.
    Thus we backport it, so that it will appear in the next maintenance
    version of automake (1.11.3).

Of course, you could explicitly state that adding a link to a mailing list
discussion as a shortcut to avoid writing a good CL entry (or worse, proper
code comments) is a big huge no-no.  I agree 100% with that.

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

> [SNIP]

I'll try to reply to the rest of your mail tomorrow.

Thanks,
  Stefano

[Stefano Lattarini]

On 01/17/2012 10:16 PM, Alfred M. Szmidt wrote:
>
> [SNIP parts I've already replied to]
>

>    >    + @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)
>
> You can do similar in THANKS.
>

But doing that in the commit message is more natural, since it easily and
naturally keeps the thanking near to the change for which it is warranted.
It make things self-explanatory.  Also, for projects with multiple branches,
Keeping the THANKS file simple and linear (with only additions of new names
and e-mails) avoids potential spurious merge conflicts in the THANKS file
itself.

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

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

>      "Report and initial patch by Zack Weinberg, test cases added by
>       Stefano Lattarini."
>
This is a bad example OTOH, I agree.

[SNIP good objections to my bad example]

> The CL header should state who _wrote_ the change; not who commited it.
>
I definitely know and I absolutely agree.  Sorry if I gave a different
impression.

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

OTOH, its exact format can be left more flexible, since different projects has
already different policies, all with their pros and cons, and no one of which
is clearly superior to the other ones (here we are in the realm of tastes and
opinions).

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

Regards,
  Stefano

[Alfred M. Szmidt]

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

   > 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_!

   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.

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

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