6.8.1 Change Log Concepts

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.

The change log file is normally called ‘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 ‘ChangeLog’ file using rcs2log; in Emacs, the command C-x v a (vc-update-change-log) does the job.

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 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 copyright records.

However, sometimes it is useful to write one line to describe the overall purpose of a batch of changes.

The easiest way to add an entry to ‘ChangeLog’ is with the Emacs command M-x add-change-log-entry. An entry 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.