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:

• Generation of useful ChangeLog files from VCS logs becomes more difficult if the change log entries don’t list the modified functions/macros, because VCS commands cannot reliably reproduce their names from the commit information alone. For example, when there is a change in the header part of a function definition, the heading of the diff hunk as shown in the VCS log commands will name the wrong function as being modified (usually, the function defined before the one being modified), so using those diffs to glean the names of the modified functions will produce inaccurate results. You will need to use specialized scripts, such as gnulib’s vcs-to-changelog.py, mentioned below, to solve these difficulties, and make sure it supports the source languages used by your project.
• While modern VCS commands, such as Git’s git log -L and git log -G, provide powerful means for finding changes that affected a certain function or macro or data structure (and thus might make ChangeLog files unnecessary if you have the repository available), they can sometimes fail. For example, git log -L doesn’t support syntax of some programming languages out of the box. Mentioning the modified functions/macros explicitly allows finding the related changes simply and reliably.
• Some VCS commands have difficulties or limitations when tracking changes across file moves or renames. Again, if the entities are mentioned explicitly, those difficulties can be overcome.
• Users that review changes using the generated ChangeLog files may not have the repository and the VCS commands available to them. Naming the modified entities alleviates that problem.

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.