Re: changelog format

[Thien-Thi Nguyen]

() Stefano Lattarini <address@hidden>
() 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}[, @address@hidden: @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  <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".
+ @end verbatim
+

  @node Man Pages
  @section Man Pages