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?

Potboiler

Have you thought about using a pre-commit hook that updates the changelog before the commit? – Sashasashay

@Dave1010: The question is more aimed at defining what messages that should go in the changelog, not how to update it. I've tried to reformat the question, thanks for a valid comment though! (And I agree that a hook might do it, post-commit though; or as part of the build/deploy script.) – Potboiler

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.

Assumptive

This sounds like an acceptable solution, but I need some clarification. How do you work with annotate (or blame), and why is it more useful than something like git commit --amend? Is it because it's on another level of priority or something? (Good references would help :)) The approach would then be "get all messages" (be it messages of the previously stated kind) "since the previous tag and show them in a nice list". – Potboiler

Sorry, I don't know why I said "git annotate". "git notes" is what I meant; I edited the answer. – Assumptive

very nice, I did not know about git notes until now. Do you have any good reference of traversing the log diff-by-diff or anything smarter, before applying the notes? Giving you the points meanwhile! – Potboiler

Do you want just 'git log -p' or something more specific? – Assumptive

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!

Camelopardalis

yeah, I'm starting to realize that "automatic" should refer to listing the right commits to pick essential commits from, rather than selecting them based purely on the current intention of a commit (like when "Fixed bug #124" doesn't really fix bug #124, but a later commit indeed does fix that bug). Thanks! – Potboiler

Answer 3

Have a look at vclog.

Pustulate

This is exactly what I was looking for, amazing piece of software. – Depositary