Circumstances in which ChangeLog format is no longer useful

[Joseph Myers]

I would like to suggest that there are certain circumstances in which it 
is no longer useful to write descriptions of changes in the ChangeLog 
format described in the GNU Coding Standards, and in which writing such 
descriptions serves to add significant extra work to maintaining a 
package, and serves to discourage contributions, without providing any 
corresponding benefit.  In these circumstances, I would suggest that the 
GNU Coding Standards should no longer require such logs to be maintained 
in that format or included in releases.

The conditions I propose (with rationale) are:

1. The package has a public version control system.

(Rationale: this ensures people can see what changed, just as with 
ChangeLogs, but can see *exactly* what changed rather than just the brief 
descriptions.)

2. The version control uses a distributed version control system.

(Rationale: this ensures people can get a complete copy of the history of 
what changed, as they can with ChangeLog files in releases.)

3. Commits are made for each logical change, not batched into a commit per 
release or per day or other such batching.

(Rationale: this ensures as much separation of logically separate changes 
as there would be in a ChangeLog file.)

4. The version control system tracks authors of changes, not just 
committers, or is used in a way that tracks authors.

(Rationale: authorship is relevant for copyright purposes.)

5. Commit messages describe the logical "what" changed (but don't 
necessarily describe the physical "what" at the level of changes to 
individual files and functions).

(Rationale: the logical "what" is useful information at the human level 
for understanding the change.  Listing individual changed files and 
functions both duplicates the information available from the version 
control system, and is at the wrong level for understanding the change for 
most purposes.  It's normal in glibc, for example, for a change to affect 
many separate files and named entities in those files, in ways that are 
repetitive but not repetitive enough to use e.g. "All callers changed", 
and which the ChangeLog format does not provide a good fit to or result in 
useful information about the changes not available from version control.)

In my proposal, *existing* ChangeLogs would still need to be kept to the 
extent that past commit logs do not meet those requirements, but it would 
not be required to maintain such files in future if those requirements are 
met, and nor would commit logs need to be convertible automatically to the 
ChangeLog format.

Now for how these meet all the purposes of ChangeLog files as described in 
the GNU Coding Standards:

  Keep a change log to describe all the changes made to program source
  files.  The purpose of this is so that people investigating bugs in the
  future will know about the changes that might have introduced the bug.
  Often a new bug can be found by looking at what was recently changed.
  More importantly, change logs can help you eliminate conceptual
  inconsistencies between different parts of a program, by giving you a
  history of how the conflicting concepts arose and who they came from.

All this information is available in version control.

  You can think of the change log as a conceptual ``undo list'' which
  explains how earlier versions were different from the current version.
  People can see the current version; they don't need the change log to
  tell them what is in it.  What they want from a change log is a clear
  explanation of how the earlier version differed.  Each @dfn{entry} in
  a change log describes either an individual change or the smallest
  batch of changes that belong together, also known as a @dfn{change
  set}.

All this information is available in version control, provided point 3 
above (commits for each logical change) is followed.

  For later reference or for summarizing, sometimes it is useful to
  start the entry with a one-line description (sometimes called a
  @dfn{title}) to describe its overall purpose.

This is standard practice for git commit messages.

  In the past, we recommended not mentioning changes in non-software
  files (manuals, help files, 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.

All files are automatically included in version control logs.

  The change log file is normally called @file{ChangeLog} and covers an
  entire directory.  Each directory can have its own change log, or a
  directory can use the change log of its parent directory---it's up to
  you.

  Another alternative is to record change log information with a version
  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.

Because the problem with ChangeLogs, as seen in glibc and elsewhere, is 
with needing to write descriptions in a particular format, at a level that 
is not useful for human understanding of the changes while not being as 
detailed as the exact changes themselves in version control, being able to 
generate ChangeLogs from version control using suitably-formatted log 
messages does not address the issue.

  For changes to code, there's no need to describe the full purpose of
  the changes or how they work together.  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, how to call it, and so on.

  For changes to files that do not support a comment syntax (e.g., media
  files), it is ok to include the full explanation in the change log file,
  after the title and before the list of individual changes.

This is unaffected by describing changes as the logical "what" changed 
rather than at the level of all the individual files and functions.

  The easiest way to add an entry to @file{ChangeLog} is with the Emacs
  command @kbd{M-x add-change-log-entry}.  An individual change 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.

This form of description is exactly what's the problem.  In the presence 
of ubiquitous distributed version control, writing this style of 
description is the equivalent of:

  /* Add 1 to i.  */
  i++;

(that is, just repeating the immediately obvious meaning of the history 
that everyone can see, and so effectively serving to hide what's actually 
interesting about the history at a human level and *should* be described).

  It's important to name the changed function or variable in full.  Don't
  abbreviate function or variable names, and don't combine them.
  Subsequent maintainers will often search for a function name to find all
  the change log entries that pertain to it; if you abbreviate the name,
  they won't find it when they search.

  For example, some people are tempted to abbreviate groups of function
  names by writing @samp{* register.el (@{insert,address@hidden)};
  this is not a good idea, since searching for @code{jump-to-register} or
  @code{insert-register} would not find that entry.

People can use "git annotate" and similar tools to identify changes to an 
individual function or other section of code, without needing descriptions 
to have been written at the level of what changed in that function that 
duplicate the version control history showing those changes exactly.

  Separate unrelated change log entries with blank lines.  Don't put
  blank lines between individual changes of an entry.  You can omit the
  file name and the asterisk when successive individual changes are in
  the same file.

This is served by point 3 above.

  Break long lists of function names by closing continued lines with
  @samp{)}, rather than @samp{,}, and opening the continuation with
  @samp{(} as in this example:

This is irrelevant in my proposal, as a formatting detail.

  When you install someone else's changes, put the contributor's name in
  the change log entry rather than in the text of the entry.  In other
  words, write this:

This is covered by point 4 above.  With git, you would commit with 
--author (if there are multiple authors, they'd still need mentioning 
explicitly in the commit message).

I don't think the remaining parts of the GNU Coding Standards description 
of ChangeLogs really need such annotation, since they are about details of 
formatting rather than purpose.  But when the formatting description gets 
into details of how to describe conditional changes and to describe the 
part of an entity changed, that is even more like the "Add 1 to i." 
comment, attempting to duplicate in English complicated conditions that 
are much more simply read directly from the diffs from version control 
whenever someone wants to have that information.

-- 
Joseph S. Myers
address@hidden