Next: , Up: Change Logs   [Contents][Index]


6.8.1 Change Log Concepts and Conventions

You can think of the change log as a conceptual “undo list” which states 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 changeset.

It is a good idea to start the change log entry with a header line: a single line that is a complete sentence which summarizes the changeset. If you keep the change log in a VCS, this should be a requirement, as VCS commands that show the change log in abbreviated form, such as git log --oneline, treat the header line specially. (In a ChangeLog file, the header line follows a line that says who was the author of the change and when it was installed.)

Follow the change log entry’s header line with a description of the overall change. This should be as long as needed to give a clear description. Pay special attention to aspects of the changeset not easily gleaned from the diffs or from the names of modified files and functions: the overall idea of the change and the need for it, and the relations, if any, between changes made to different files/functions. If the change or its reasons were discussed on some public forum, such as the project’s issue tracker or mailing list, it is a good idea to summarize the main points of that discussion in the change’s description, and include a pointer to that discussion or the issue ID for those who’d like to read it in full.

The best place to explain how parts of the new code work with other code is in comments in the code, not in the change log.

If you think that a change calls for explanation of why the change was needed—that is, what problem the old code had such that it required this change—you’re probably right. Please put the explanation in comments in the code, where people will see it whenever they see the code. An example of such an explanation is, “This function used to be iterative, but that failed when MUMBLE was a tree.” (Though such a simple reason would not need this kind of explanation.)

The best place for other kinds of explanation of the change is in the change log entry. In particular, comments usually will not say why some code was deleted or moved to another place—that belongs to the description of the change which did that.

Following the free-text description of the change, it is a good idea to give a list of names of the entities or definitions that you changed, according to the files they are in, and what was changed in each one. See Style of Change Logs. If a project uses a modern VCS to keep the change log information, as described in Change Logs, explicitly listing the files and functions that were changed is not strictly necessary, and in some cases (like identical mechanical changes in many places) even tedious. It is up to you to decide whether to allow your project’s developers to omit the list of changed files and functions from the log entries, and whether to allow such omissions under some specific conditions. However, while making this decision, please consider the following benefits of providing the list of changed entities with each change:

For these reasons, providing lists of modified files and functions with each change makes the change logs more useful, and we therefore recommend to include them whenever possible and practical.

It is also possible to generate the lists naming the modified entities by running a script. One such script is mklog.py (written in Python 3); it is used by the GCC project. Gnulib provides another variant of such a script, called vcs-to-changelog.py, part of the vcs-to-changelog module. Note that these scripts currently support fewer programming languages than the manual commands provided by Emacs (see Style of Change Logs). Therefore, the above mentioned method of generating the ChangeLog file from the VCS commit history, for instance via the gitlog-to-changelog script, usually gives better results—provided that the contributors stick to providing good commit messages.


Next: , Up: Change Logs   [Contents][Index]