Martin Pool's blog

Mail me RSS Bazaar distcc Canonical is hiring! flickr

Why Changelogs?

In many GNU packages like gcc or emacs you'll see a ChangeLog file containing a description of all of the changes to the package. I'd always thought of them as a vestige of a previous era before CVS, but bje recently made a pretty good argument for continuing to use them.

Here's a sample from emacs's ChangeLog, for any readers who aren't familiar with the form:

2003-09-23  Dave Love  <fx@gnu.org>

        * configure.in: Check
          members of struct ifreq.

2003-09-14  Kim F. Storm  <storm@cua.dk>

        * configure.in: Add
          checks for sys/ioctl.h and net/if.h.

2003-09-12  Luc Teirlinck  <teirllm@mail.auburn.edu>

        * Makefile.in (install-arch-indep, uninstall): Add SES manual.

2003-08-18  Lute Kamstra  <Lute.Kamstra@cwi.nl>

        * configure.in: Revert
          the change of 2003-07-29 as GTK+ 2.2 is not
        required anymore.

2003-08-07  Andrew Choi  <akochoi@shaw.ca>

        * configure.in [powerpc-apple-darwin*]:
          Use the -no-cpp-precomp
        option instead of -traditional-cpp for CPP.

There's a text format for listing changes and then also a description in the GNU coding standards of what information ought to be in the entries. This list of what was changed, when, and by whom is pretty similar to what you might see in a CVS history.

So if you're storing your project in CVS or some other revision control system, then keeping a ChangeLog as well is redundant. Indeed, if you keep the ChangeLog in CVS then every comment is literally being stored twice...

The main reason for using a ChangeLog is that it travels with the source it describes. Years in the future if somebody obtains the source they can still see its history, even if they no longer have access to the version control system. It's fairly common for projects to move between different vc systems over their lifetime. It's not unheard of for a vc system to be lost entirely, leaving only a set of tarballs as a record.

If some other party wants to fork the project, or develop it offline for a while before merging back, then the ChangeLog gives some hope that their history will be recorded.

Another advantage is that it's easy to scan through the log for mentions of a particular function. Easier than with any vc system I know of, at least if the log is well written.

I've recently got hold of a few source tarballs written by parties unknown, and existing in different versions with no clear indication of when things were changed or why. If they'd come with ChangeLogs, things might be a bit easier. Of course the kind of person who omits even a README might not write a ChangeLog, but if somebody else had started one perhaps they might have continued it.

If we all used a version control system like arch or bitkeeper that carried history with the source then perhaps this might be less necessary. But even then there's no guarantee that every person who gets the source in the future will want to keep using that system...

If things are being kept in both CVS and a ChangeLog, it ought to be easy to use a little script or macro to keep them in sync.

There are scripts such as cvs2cl that produce a ChangeLog for CVS sources.

GNU emacs also has commands to integrate version control and ChangeLogs.

Some projects require that ChangeLog entries be submitted with patches. This means an explanation of the change in the originator's own words always gets into the project history. If the ChangeLog standards are enforced then the entry will have a level of detail and preciseness that might not be present in an informal description of the change.

As with any history logs, there is a small challenge in writing descriptions that will be comprehensible and useful to people reading them months or years hence.

I'm going to try this for a while...

posted Mon 17 Nov 2003 in /software/vc/changelogs | link

Copyright (C) 1999-2007 Martin Pool.