Re: Circumstances in which ChangeLog format is no longer useful

[Alfred M. Szmidt]

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

I think that rationale is incorrect, just because you have a public
version control system does not mean that you can see what actually
changed.  Going through multiple megabytes of diffs is not feasible,
and searching for when something was renamed, added, removed, etc is
something no tool is capable of providing.

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

How would the information that is normally available in a ChangeLog
file be populated if all that information is in the VCS?  That would
still be needed for normal tarballs and the like when VCS is out the
window.

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

This is I think a good idea, the bunching of ChangeLog entries always
feelt a bit weird.

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

When making tarball releases this information needs to be available
somehow as well.

   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.

I am not sure I understand why it is wrong, to be able to understand
how something came to be one needs to look at how things changed --
and only way to do that is with a ChangeLog entry.

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

Knowing that all callers have been change is I think useful
information, why do you think the opposite?

   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.

Being able to generate the ChangeLog file is I think important for
posterity, tarball releases lack any kind of history.  History has a
really bad memory, just because one uses a VCS today doesn't mean that
this will be available in 10, 20, 30 years in any usable format, or it
might vanish completley.

I've saved a few projects that used some sort of VCS, but was lost for
different reasons, and having had ChangeLog files would have saved
many many hours of headaches.  Now all that is left is a tarball, with
no information about who, when, or what was changed.

   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.

If you put ChangeLog entries in the commit message, then yes this
information will be available.  But if you discard ChangeLog entries
completley, I do not see how it can be available.  "annotate", "diff"
don't provide a human readable and searchable means to go through
history.  The information also becomes totally lost as soon as you
discard the VCS (i.e. when doing releases).

     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.

We shouldn't assume that everyone uses git.  The above text can apply
to any version control system, or even the lack of one.

     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.

I think the point of the above paragraph was that non-software files
were not useful when you need to track bugs in software.

     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.

Are we talking about the entries, or the actual ChangeLog file?  Many
projects have abandoned keeping actual ChangeLog files, and extracting
this information when making a tarball release since they cause the
typical merge conflics and what nots.  If you are refering to the
ChangeLog entries, I am not sure what problems you are refering to.

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

I don't think the comparison is fair, the point of the ChangeLog files
is to be able to undo changes.  The comment above doesn't actually
provide anything, a more apt comparison would have been:

     /* Change #1 was: Add pi to i.  */
     /* Change #2 was: Add 1 to i.  */
     i += 2;

That information is very useful when digging for bugs, and
understanding how a code base was changed.  Just because one uses VCS
doesn't mean that history is automatically available to everyone,
someone still needs to write a commit message of some sort (i.e. the
ChangeLog entry)

Sifting through multi-megabyte diffs isn't very fun when trying to get
a birds eye view of what actually happened in a code base, and this is
where ChangeLog entries are super useful and I'd argue totally
nessecary for any code base.

     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.

There is still a need to make tarball releases, where such tools are
not available, but also for legal reasons, and for maintainability.

It also makes a strong assumption on tools, and history has shown that
tools come and go but text files stay. :-)

Cheers, Alfred.