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.
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.
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.
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.
We make extensive use of these at the day job. It is a lifesaver. If I ever get around to using bug tracking for myself, I'm certainly going to continue the practice.
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.
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.
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?"
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
