Paul Biggar's blog archive

Great commit messages

roc and jimb write great commit messages. As well as fulfilling the basics requirements of listing the reviewer, bug number, etc, they add enough context that you don’t need to crawl through bugzilla to get a reasonable understanding of the problem.

Not that linking to bugzilla is bad - there is all manner of context in there that is really important to track. But there are also dead-ends, dups, noise, discussion, politics, reviews, and other things that don’t really help get a high-level overview of the problem.

I used to write better messages in projects I committed to in the past (mostly phc, following to a lesser extent the example I saw on the gcc-patches list), but since it wasn’t the Mozilla way, I felt like I was freed from the burden. And it is a burden: writing concise but descriptive log messages takes time and effort. But considering the work that goes into a patch, the few minutes to edit the message seem worth it.

The gcc-patches list is the best place I’ve seen this done; for an epic example, consider a 2004 post by Jakub Jelinek. Bear in mind that long messages like this are for code reviewers, not for posterity, so it’s solving a slightly different problem. However, for people following along at home, they have the same benefit.

One problem with writing better messages is that they aren’t really obvious. In hg log, you need the -v flag to even make them appear, and the default view over at doesn’t show them. However, it’s pretty apparent in the log view how superior these messages are. Good revolutions start from the bottom, so I’m going to follow roc and jimb’s examples.

[1] For the non-Mozillians in the audience, Mozilla’s coding standards require that commit messages include the bug number, the reviewer name, and some other information such as a super-reviewer, if they exist. Since they don’t specify that you need to describe the bug in any detail, we end up with terse, one-line descriptions of the commits. However, our tools link to bugzilla number, so we do have easy access to the full history of the problem.