Re: changelog format

[Thien-Thi Nguyen]

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:
+
address@hidden
+ TITLE
+ * ENTRY
address@hidden 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:
+
address@hidden @asis
address@hidden 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.
+
address@hidden reference to external resources
+This includes bug report IDs, URIs to related mailing list threads, etc.
+Remember to choose URIs that are permanently accessible.
+
address@hidden reference to another change
+This is useful when a change is a fix or continuation
+of a previous change.
+
address@hidden 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.
address@hidden FIXME: Mention THANKS in maintain.texi; xref it.
address@hidden 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.
address@hidden FIXME: Maybe a reference to gnu-vcs-fu is better.
address@hidden 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:
address@hidden, @address@hidden: @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

address@hidden Change Log Examples
address@hidden Change Log Examples
+
+Here are two slightly-edited examples from coreutils and Serveez,
+respectively.
+
address@hidden Use @verbatim to avoid ugly over-indentation w/ @example.
address@hidden
+2011-12-08  Jim Meyering  <address@hidden>
+
+        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  <address@hidden>
+
+        [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".
address@hidden verbatim
+

 @node Man Pages
 @section Man Pages