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. Each entry in a change log describes either an individual change or the smallest batch of changes that belong together, also known as a change set. For later reference or for summarizing, sometimes it is useful to start the entry with a one-line description (sometimes called a title) to describe its overall purpose.

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.

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.

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.

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.

The easiest way to add an entry to ChangeLog is with the Emacs command 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.