Quality of commit messages

I’ve been subscribed to the Git mailinglist for three weeks now, and I’ve finally seen in action what was already imaginable by looking at their git log history: they not only review the code for the patches that go in (as in many other projects, that is), but also review the accompanying commit messages, in order to ensure they meet certain quality standards. More than once already I’ve seen an otherwise-fine patch get resubmitted in order to gain a more meaningful or thorough commit message.

I’m sure there are more projects that do this, but alas, I haven’t been in any of them (nor in that many projects in general, for that matter). It’s very exciting for me to see it in action, because quality commit messages are high in my “Grokking VCS” list.

Ideally, a commit message conveys all the necessary information the maintainer of a project needs to understand your patch and its benefits, in particular those bits that don’t fit as comments in the code. If you have to accompany your patch with rationales, wouldn’t it make sense to include a condensed version of them in your commit message? If you’re writing messages for a project of your own, please think of future people dealing with your code, particularly if it’s a public project. (It takes discipline in addition to being convinced of it, though.)

Commit messages are also great because they allow you to be verbose, without cluttering the code with information that’s only relevant in the context of the change, and not to the final code. There is however an (actually-not-so-fine) line between what should be in the commit message, and what should be as comments in the code, and I think we commit message enthusiasts should watch out for that. Take, for example, 39c19ce. I think a short comment saying “Don’t call rev-parse for each blamed line” would have been a perfect companion.

There must be somewhere a document explaining with more detail what makes a good commit message. If you would recommend any, please let me know (but I’m not interested in documents that explain how to format your commit messages).