On Commit Messages

http://who-t.blogspot.com/2009/12/on-commit-messages.html

by edw519 • 17 years ago

45 23 17 years ago

who-t.blogspot.com

diN0bot3• 17 years ago

i'm ambivalent about where the right place is to answer the 3 questions posted by the OP.

on the one hand, it seems efficient to put meta-data in the commit rather than clouding the code itself. on the other hand, i'm much more likely to go back to a piece of code and reread my comments and architectural diagrams then visit the repo logs. if documentation is too big or orthogonal to go in a class or function comment, then i put it in the docs folder.

gregwebs2• 17 years ago

Placing info in the code or docs seems useful for a feature, but a bugfix may not require any code documentation, particularly if there is a test case for it.

diN0bot3• 17 years ago

i often leave a code comment near a bug fix if there was something non-obvious that i messed up the first time. eg, "sleep required here because blahity blah".

it is true that writing a larger overview of, say, the thread timings is useful near the thread timing tests. i'm not above just putting a thread timing explanation in the docs folder though, especially if that influences much of the architecture and coding conventions elsewhere.

commit messages seem nice to look back on, but anything that impacts the current code state should be present in the current docs. otherwise new developers and maintainers have to look through a chronology of logs messages, which presents the same problem as blogs and hacker news compared to say wikipedia.

jparise2• 17 years ago

Commit descriptions describe the change, which is very often different than the design of the code itself.

My approach is to use detailed descriptions in both places: commit logs track the evolution of the source tree, and comments/documentation describe the design and implementation of the source tree at a snapshot in time (e.g. now/tip).

diN0bot3• 17 years ago

good point. i guess i'm overvaluing the now/tip docs. i definitely delete old docs since that just confuses everything.

when i reach that point where i start wanting to revert the repo or backtrack on changes then commit docs will make much more sense. i still leave a good commit message when i can but....documenting the now/tip in the code is far more useful to me currently.

ams6110• 17 years ago

What I like to do is reference a tracking number from the issue/bug tracking system in my commit messages. Yes, this has some possible pitfalls, e.g. the source code may outlive the issue tracking system, or may change owners without the issue history coming along.. but it works well in practice.

gregwebs2• 17 years ago

its best when your bug tracker can automatically link to issue numbers and commit numbers.

petewarden• 17 years ago

Having a URL scheme for bugs was a massive help at Apple, the standard for commit messages was including something like "Fix for rdar://17373108".

makecheck• 17 years ago

Using svn with Trac, for example, one can use "r1234" to refer to a revision from a ticket, or "#123" to refer to a ticket number from a commit message.

modoc• 17 years ago

Yes! JIRA + Mylyn (for Eclipse) makes this automatic and let's you see the commits made for the ticket in Jira, and link from the commit e-mails to the Jira ticket(s). Huge fan.

steveklabnik• 17 years ago

Lighthouse not only does this, but lets you modify tickets with your commits (through Github, at least). Pretty cool.

jparise2• 17 years ago

Some SCM systems have per-commit metadata facilities. For example, Perforce changelists can be tagged with a "job" field, which could be a bug identifier.

prodigal_erik2• 17 years ago

Microsoft's system was pretty nice. Once you tell the bug database which commit(s) fix a bug (sometimes backed by a set of uploaded crash dumps), it keeps track of which branches the fix has been merged into, so when QA deploys a build they know what is now available to regress. They licensed Perforce for source control (rather than SourceSafe, which they long since stopped recommending anyone use, look directly into, or feed after midnight) but don't use its "job" features for this.

Though it sounds like they're going to replace all this with Visual Studio Extra Crispy Team System for Epic Workgroups Prime. Best of luck prying everyone I met off vim and build.exe, guys.

cool-RR• 17 years ago

In my opinion, unless your project already has excellent documentation, you shouldn't spend much time or thought documenting your commits.

Making detailed commit messages is "documenting the process". Making code documentation is documenting the product. The latter, in my opinion, is much more important.

kscaldef• 17 years ago

I disagree. Good commit messages also document the product. They should describe or reference features requested, bug reported, and the _why_ of the change at least as much as the _what_ of the change.

jonursenbach• 17 years ago

Let us know how that works out 6 months from now when you have a regression issue and you're trying to track it down.

tetha• 17 years ago

In fact, I currently experience the very unintuitive thing that I can create extremely detailed commit messages using git without investing much more time (at the moment, I need to spend around 5-10 additional minutes after an hour or two of development while getting a precise log of added functionality and/or refactorings performed).

The thing I am currently investigating is to commit extremely often during development and then use rebase to squash all of these extremely tiny changes into the actual change. Don't come with the "atomic single changes"-stick after me for squashing local commits, because when I said extremely tiny, I meant extremely tiny. Currently, I commit pretty much whenever a new test is red or the last red test is green, or after a single refactoring step. Given that, I end up with a very detailed sequence of steps and changes I made. Once you are done then, you can just add a summary line, a quick paragraph explaining the reason for those changes and reformat the previous commit messages into a (hieraichally structured) list of detailed changes.

I can just repeat this: Doing this is almost no noticeable overhead (it's just a git commit -a -m "Move method: Foo.bar -> Bar" after a successful build and some rebasing eventually, which takes 5 - 10 minutes after an hour or two of development) and massively improved my commit messages.

bcl• 17 years ago

Excellent points. I have found myself making some of these mistakes (ie. whitespace changes mixed with other changes) and do feel bad about them later.

I'm going to post a link to this at the top of our project's Trac page to remind everyone of the (a) right way to do it.

roundsquare2• 17 years ago

I used to work with a guy who wrote horrible commit messages. My (least) favorite was "works better." This was especially annoying because his code generally didn't go through review and was pushed into production within minutes. So any problem with the new code and we'd need to stare at the diff (which was often very complex) and try to answer the 3 questions in the article plus why it caused a problem.

Mind you - this was a guy with a few decades of experience.

prodigal_erik2• 17 years ago

Could be worse, at least he was claiming it was done. I frequently see several completely unrelated changes committed together with the comment "wip" (which stands for "work in progress") and these aren't from just one dev. Drives me nuts. "Was this finished?" "Did QA have any idea what you were sneaking in?"

roundsquare2• 17 years ago

at least he was claiming it was done

True enough, but we never what he was claiming was done. It was just better.

Though I admit, yours is much worse...

matty• 17 years ago

What is worse, bad commit messages or no commit messages at all? Having to diff through no commit message changes is the bane of my existence. Yes I have brought this up to my supervisors multiple times, sometimes they are the culprits.

On Commit Messages

Related Stories