

On Commit Messages - edw519
http://who-t.blogspot.com/2009/12/on-commit-messages.html

======
ams6110
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.

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

~~~
makecheck
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.

~~~
patio11
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.

------
roundsquare
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_erik
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?"

~~~
roundsquare
_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...

------
bcl
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.

------
matty
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.

------
diN0bot
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.

~~~
jparise
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).

~~~
diN0bot
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.

------
cool-RR
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.

~~~
jonursenbach
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.

