view release on metacpan or  search on metacpan

src/subversion/doc/programmer/WritingChangeLogs.txt  view on Meta::CPAN

This is an essay by Jim Blandy <jimb@redhat.com> on maintaining
ChangeLog entries.  

Although Subversion generates its ChangeLogs from svn log data,
instead of keeping independent ChangeLog files, most of the advice
below is as applicable to cvs log messages as to ChangeLog entries.


Maintaining the ChangeLog
=========================

A project's ChangeLog provides a history of development.  Comments in
the code should explain the code's present state, but ChangeLog
entries should explain how and when it got that way.  The ChangeLog
must show:

* the relative order in which changes entered the code, so you can
  see the context in which a change was made, and

* the date at which the change entered the code, so you can relate the
  change to outside events, like branch cuts, code freezes, and
  releases.

In the case of CVS, these refer to when the change was committed,
because that is the context in which other developers will see the
change.

Every change to the sources should have a ChangeLog entry.  The value
of the ChangeLog becomes much less if developers cannot rely on its
completeness.  Even if you've only changed comments, write an entry
that says, "Doc fix."  The only changes you needn't log are small
changes that have no effect on the source, like formatting tweaks.

In order to keep the ChangeLog a manageable size, at the beginning of
each year, the ChangeLog should be renamed to "ChangeLog-YYYY", and a
fresh ChangeLog file started.


How to write ChangeLog entries
------------------------------

ChangeLog entries should be full sentences, not sentence fragments.
Fragments are more often ambiguous, and it takes only a few more
seconds to write out what you mean.  Fragments like `New file' or `New
function' are acceptable, because they are standard idioms, and all
further details should appear in the source code.

The log entry should mention every file changed.  It should also
mention by name every function, variable, macro, makefile target,
grammar rule, etc. you changed.  However, there are common-sense
exceptions:

* If you have made a change which requires trivial changes throughout
  the rest of the program (e.g., renaming a variable), you needn't
  name all the functions affected.

* If you have rewritten a file completely, the reader understands that
  everything in it has changed, so your log entry may simply give the
  file name, and say "Rewritten".

In general, there is a tension between making entries easy to find by
searching for identifiers, and wasting time or producing unreadable
entries by being exhaustive.  Use your best judgement --- and be
considerate of your fellow developers.

Group ChangeLog entries into "paragraphs", separated by blank lines.
Each paragraph should be a set of changes that accomplish a single
goal.  Independent changes should be in separate paragraphs.  For
example:

    1999-03-24  Stan Shebs  <shebs@andros.cygnus.com>

            * configure.host (mips-dec-mach3*): Use mipsm3, not mach3.

            Attempt to sort out SCO-related configs.
            * configure.host (i[3456]86-*-sysv4.2*): Use this instead of
            i[3456]86-*-sysv4.2MP and i[3456]86-*-sysv4.2uw2*.
            (i[3456]86-*-sysv5*): Recognize this.
            * configure.tgt (i[3456]86-*-sco3.2v5*, i[3456]86-*-sco3.2v4*):
            Recognize these.

Even though this entry describes two changes to `configure.host',
they're in separate paragraphs, because they're unrelated changes.
The second change to `configure.host' is grouped with another change
to `configure.tgt', because they both serve the same purpose.

Also note that the author has kindly recorded his overall motivation
for the paragraph, so we don't have to glean it from the individual
changes.

The header line for the ChangeLog entry should have the format shown
above.  If you are using an old version of Emacs (before 20.1) that
generates entries with more verbose dates, consider using
`etc/add-log.el', from the GDB source tree.  If you are using vi,
consider using the macro in `etc/add-log.vi'.  Both of these generate
entries in the newer, terser format.

One should never need the ChangeLog to understand the current code.
If you find yourself writing a significant explanation in the
ChangeLog, you should consider carefully whether your text doesn't
actually belong in a comment, alongside the code it explains.  Here's
an example of doing it right:

  1999-02-23  Tom Tromey  <tromey@cygnus.com>

          * cplus-dem.c (consume_count): If `count' is unreasonable,
          return 0 and don't advance input pointer.

And then, in `consume_count' in `cplus-dem.c':

   while (isdigit ((unsigned char)**type))
     {
       count *= 10;
       count += **type - '0';
       /* A sanity check.  Otherwise a symbol like
         `_Utf390_1__1_9223372036854775807__9223372036854775'
         can cause this function to return a negative value.
         In this case we just consume until the end of the string.  */
      if (count > strlen (*type))