Skip to main content

What do you try to leave in your commit messages?

Posted by kohsuke on February 25, 2010 at 10:09 AM PST

James Lorenzen had an excellent blog post about the importance of a descriptive commit comment. I can't agree more.

Unfortunately, I think getting better at leaving better commit messages take trial and error — the way I've learned it is by getting frustrated by the lack of commit messages. So in the spirit of encouraging everyone (including myself) to do a better job, I thought I'd list up what I try to leave in the comments.

  • Bug ID. In fact, bug/commit association is so useful that often you use (or write) programs that analyze these relationship, so it's preferrable for this information to be machine readable.
  • URL to the e-mail in the archive that prompted me to produce a change. In Hudson, often a conversation with users reveal an issue or an enhancement that results in a commit. This URL lets me retrieve the context of that change, and I find it tremendously useful.
  • If the discussion of a change was in IM, not e-mail, I just paste the whole conversation log, as they don't have an URL. Ditto if the e-mail was sent to me privately.
  • The input value and/or the environment that caused a misbehavior. In Hudson, I have this one method that needs to do some special casing for various application servers. When I later generalized it a bit more, commit messages that recorded the weird inputs from WebSphere, OC4J, and etc. turned out to be very useful.
  • For a fix, a stack trace that indicates the failure. Sometimes I misdiagnose the problem, and later when I suspect I did, being able to see the original output really helps me.
  • If I tried/considered some other approaches to the problem and abandoned them, record those and why. I sometimes look back my old change and go "why did I fix it this way — doing it that way would be a whole lot better!", only to discover later that "ah, because this won't work if I've done that!", and I knew I've gone through the same trail of thoughts before. If I'm in a middle of a big change and decide to abandon a considerable portion of it, I sometimes even commit that and roll it back, just so that I can revisit why I abandoned it later.
  • If a change should have been logically a part of a previous change, just say so. If I happen to know the commit ID of the previous change, I definitely leave that, but if I don't remember it, I still try to point to where that previous change was, like roughly when it was made, which file it was made, who did it, etc, so that future myself can narrow down the search space if I need to find it.

What do you try to leave in your commit messages?

Related Topics >>


Other info

I usually include IM, emails, stack traces, etc in the bug itself. Bug IDs are usually auto-linked. However, if it is a workaround to a bug on another site (say in Sun's Bug Database for example) I usually include the URL to the bug. I also tend to specify if it is a "incremental checkin" (say for a new feature)

Communicating Intent

Something automated that resolves issues when certain keywords are used (like your scm-issue-link) is awesome for a few reasons:
  • it's useful and fun, so developers are more likely to follow the convention to best utilize the feature
  • provides integration of issue tracking and source control
Here's what I wrote for Mifos:

The "what" of a change seems to be well captured by the source control system itself; the bit I really wanted to underscore in our guide was communicating intent and providing context.
  • why did you make this change?
  • why do it the way you did?
  • does the change need merging/porting to a release branch?

This is mainly a response to a large corpus of legacy code with much veiled intent.

I also notice that I'm more likely to really use source control (logs, annotations, etc) if it is lightning fast. Moving off helped, but sourceforge still isn't fast enough. I keep a full repository mirror on my local hard drive. I can't wait until we switch to a dVCS like Mercurial.

Subversion's commit message format

Subversion has a specific commit message format we like committers to use. Mike Pilato blogged about it a couple years ago: There are also details in the Subversion HACKING guide: Mark

I must admit that my mileage

I must admit that my mileage varies whether I'm working on a paid project (so there's the time to do everything ;-) or one of my personal projects (also considering that in many of the latter group I'm the only committer, so it's less important to communicate to others). In any case, my approach is to have short commit messages with the JIRA id of the issue, and put all the verbosity in JIRA itself. In particular, I find it useful that in JIRA it is possible to customize the forms, so you can eventually give a more structured form of the information. Also, I think that a good idea is to document the link between the JIRA issue id and the test(s) involved with it (a well written test is an excellent documentation) - in the past I've even created a documenting annotation for this job, but I realize I've only used it in a discontinuous fashion.

it's a matter of policy

Where I work, there's a perforce trigger that prevents you from checking in if your checkin comments don't include the url to the bug in our bug tracking system, and a tag indicating who reviewed the code.  Makes going back into the history a _lot_ easier.

Great suggestions

Thanks for the support. Those are all excellent suggestions. Amazed someone writes more detail than me.