6.8 Change Logs

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, who they came from, and why the conflicting changes were made.

Therefore, change logs should be detailed enough and accurate enough to provide the information commonly required for such software forensics. Specifically, change logs should make finding answers to the following questions easy:

• What changes affected a particular source file?
• Was a particular source file renamed or moved, and if so, as part of what change?
• What changes affected a given function or macro or definition of a data structure?
• Was a function (or a macro or the definition of a data structure) renamed or moved from another file, and if so, as part of which change?
• What changes deleted a function (or macro or data structure)?
• What was the rationale for a given change, and what were its main ideas?
• Is there any additional information regarding the change, and if so, where can it be found?

Historically, change logs were maintained on specially formatted files. Nowadays, projects commonly keep their source files under a version control system (VCS), such as Git, Subversion, or Mercurial. If the VCS repository is publicly accessible, and changes are committed to it separately (one commit for each logical changeset) and record the authors of each change, then the information recorded by the VCS can be used to produce the change logs out of VCS logs, and to answer the above questions by using the suitable VCS commands. (However, the VCS log messages still need to provide some supporting information, as described below.) Projects that maintain such VCS repositories can decide not to maintain separate change log files, and instead rely on the VCS to keep the change logs.

If you decide not to maintain separate change log files, you should still consider providing them in the release tarballs, for the benefit of users who’d like to review the change logs without accessing the project’s VCS repository. Scripts exist that can produce ChangeLog files from the VCS logs; for example, the gitlog-to-changelog script, which is part of Gnulib, can do that for Git repositories. In Emacs, the command C-x v a (vc-update-change-log) does the job of incrementally updating a ChangeLog file from the VCS logs.

If separate change log files are maintained, they are normally called ChangeLog, and each such file covers an entire directory. Each directory can have its own change log file, or a directory can use the change log of its parent directory—it’s up to you.