Strategy for extracting messages of most useful commits to changelog

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.

Answer 2

I don't know of any such standard tool, but since you haven't gotten an answer for a while, here are some ideas:

So first, trying to avoid a CHANGELOG file, as you suggest, is probably a good idea in general because of all the merge conflicts such a file tends to cause. (Unless you happen to have a smart automatic merge tool.)

Something like a CL: or Log: prefix for easy extraction is probably a good idea. Regarding Add/Ref/Rem/Fix: (I assume that Ref and Rem stand for "Refactor" and "Remove", right?) When you're writing a changelog, I'd rather stick with free-form entries. For example, I'm not sure that refactorings belong into a changelog, and features that are high-level enough to warrant changelog entries don't usually get removed outright -- they rather get changed into some other form.

But then, how would you approach the possibility of having commit messages written just for changelogs (i.e. too high level);

I'd say, put the (CL:-tagged) high-level description in one paragraph of the commit message, and the lower level technical description in another paragraph.

or multiple messages concerning the same changelog issue.

We're talking about something like this, right?

1. (2011-01-03) CL: Changed whizbar default to 200.
2. (2011-01-11) CL: Changed whizbar default to 150, or 250 if foosnub is true.

And this is where I think the "automatic changelog" thing gets tricky. Unless you're willing to rebase and edit commit messages after the fact (like removing "CL:" from commit (1) above), I'd suggest that the only practical way to go about this is, every time you make a release, to extract all tagged paragraphs from the git log since your last release, and manually edit the resulting list, merging things like (1) and (2) above together, and turning, say, "Fixed #145", "Fixed #153", "Fixed #164" into a single line "Fixed #145, #153, and #164."

Hope I've been able to provide some inspiration. Let us know what you end up doing!

Answer 3

Have a look at vclog.