Re: changelog format

[Thien-Thi Nguyen]

() address@hidden (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}[, @address@hidden: @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