Question

The needs for this question is to

• have a changelog for managers/customers that:
  • does include “Let users have additional addresses”
  • does not include “Fixed the bug where addresses were overwritten due to X”
• avoid having to look through complete log history to find the most important commits (most often backwards incompatible) for each build
• make it as easy to read as the typical game changelog (“Fixed balance issues: X” and “Graphics driver Y rendered the game slowly”)

Today, we’re using flags in commit messages such as

Add|Ref|Rem|Fix: <msg> for the usual commit.

As such, my first stab at this would be to add another tier to those flags, for example

CL-Add: feature X (CL = changelog) and then parse all commit messages for ^CL-(Add|Ref|Rem|Fix) to add to the changelog.

But then, how would you approach the possibility of having commit messages written just for changelogs (i.e. too high level); or multiple messages concerning the same changelog issue. Perhaps the changelog messages should rather be extracted when feature-branches are merged? Are there features of SCM:s (for example git) that handles this issue for you?

Simply put: is there an industry standard strategy, or tool, for extracting useful commit messages into changelogs with ease?

Answer 1

I’ve tried this myself with little luck in the past. Basically, it’s actually more work to have every developer think, for every commit, about whether their commit message is too scary for customers or not. Developers are generally not the right person to make that decision, and doing it a bit at a time is inefficient.

After a lot of experimentation, what has worked for me is trivial: just before every release, have one person go through the git log since the last release and write down all the interesting stuff into a changelog file. This really isn’t more work than the other way; most of the work is deciding, not phrasing. And the decision process requires a particular mindset, so it’s more efficient to have one person do it in a big batch than a bunch of developers doing a tiny bit at a time. (Think of it this way: you don’t have to keep swapping the “commit message customer checking” part of the job in and out of cache.)

If you really want to tag commit messages with this sort of information, you should at least consider doing it with git notes instead of the raw commit message. Then if someone screws it up by marking the commit incorrectly as bug/feature/etc, you can fix it by updating the annotation.