ChangeLog

Software development projects usually contain some sort of ChangeLog. This page collects my notes and thoughts about this type of file.

Overview

From the Wikipedia page:

A changelog is a log or record of changes made to a project, such as a website or software project, usually including such records as bug fixes, new features, etc. Most open source projects include a changelog as one of the top level files in their distribution.

Good examples

I like the way how the following projects present their ChangeLog:

• http://cyberduck.ch/changelog/
• http://php.net/ChangeLog-5.php
• http://developer.pidgin.im/wiki/ChangeLog

I'm a Debian fan, so here is the pointer to an example from a Debian-style ChangeLog. I used to group entries under headings like this:

Thu Oct 29 2009  "Patrick Näf" <herzbube@herzbube.ch>

but since I am the sole developer on my projects, this doesn't really make sense. Besides, other projects with more than just one developer also do not use this detailed type of attribution.

How it should not be done

In a couple of projects of mine I used to document every and all changes in the ChangeLog file. My description of the file looked like this:

  This document should be continually updated, even as you code. It should
  mention even minor changes. A compilation of the most important changes
  (whether they are minor or major) can then be made and placed into the
  README document, just before a release occurs.

With time I began to doubt the wisdom of the "add everything" approach. For instance, it just doesn't make sense to duplicate SCM log messages when a simple

git log

produces all the history you want. There is also the problem of merging changes from one branch to another: Which entries to the ChangeLog should be retained if some of the changes are merged and others are not?

The current approach

Essentially, the ChangeLog should be release-centric: Its entries should be rather high-level so that the entries can be used as a source for release notes, e.g. to populate the "Changes in this release" section in the README document. Examples for things that should be included in the ChangeLog:

• Fixes for distinct bugs, with or without a bug report in the bug tracker
• New features, with or without a bug report in the bug tracker
• Other "big" changes that are noticable by the users of the software (e.g. the program icon has changed)
• Things that may not be noticable but that need to be brought to the attention of the users of the software (e.g. a license change)

ChangeLog format

General format description:

• Entries are grouped below a heading that refers to a release
• The most recent release appears at the top of the file
• The release heading contains at least the release's version number and the release date
• For a large and long-lived project, it might make sense to also add the release type to the release heading (e.g. maintenance release, major update)
• It might be a good idea to group all entries of a specific type (e.g. all bugfixes appear in a row, then all features, etc.)
• For larger projects it might also make sense to have sub-headings that group entries according to components
• Entries should be formatted like this:

[entry type] entry text [optional bug tracker entry number]

• Entry types: bugfix, feature, doc, ...

Side notes on problems not directly related to the ChangeLog

How can I identify commits that contribute to a bugfix or feature?

• If the bug or feature has a bug report or feature request in the bug tracker, the commit message must refer to the number of the bug tracker entry
• If the bug or feature has no entry in the bug tracker ??? TODO ???
  • Without doubt, the best possible solution would be to require a bug tracker entry
  • This is somewhat bureaucratic and is not really helpful if a quick fix for a very small problem needs to be implemented
  • The past has shown that the bureaucratic and dogmatic approach is subverted earlier rather than later

If I don't commit immediately, how do I keep track of what I did so that I can remember what the local changes were for?

• Honestly, this should not happen, should it? (but it certainly did, in the past)
• If in doubt, make a new branch and commit
• Or add comments to a file and use git stash