commit messages

Discussion of general topics related to the new version and its place in the world. Don't discuss new features, report bugs, ask for support, et cetera. Don't use this to spam for other boards or attack those boards!
Forum rules
Discussion of general topics related to the new release and its place in the world. Don't discuss new features, report bugs, ask for support, et cetera. Don't use this to spam for other boards or attack those boards!
User avatar
Acyd Burn
Posts: 1838
Joined: Tue Oct 08, 2002 5:18 pm
Location: Behind You
Contact:

Re: commit messages

Post by Acyd Burn »

Highway of Life wrote:What benefit would a project wide standard on commit messages have? :? I’m genuinely curious because to me, a commit message is nothing more than a very simple summary of the commit unless it was a security or bug fix, in which case it would simply be #xxxx
it helps those who want to identify the "wrong" commit sets. The numbers are only helpful if they are linked automatically.
If I want to find out what the code does, I would read through the diff from the commit log. How is sticking to a standard template for commit messages going to benefit the users and developers? Remember that the SVN is really only for those who are following development, which means you can read the code already.
I think the problem code reader points to are those developers face too from time to time... finding out where and when something got changed years ago. ;)

Image
code reader
Registered User
Posts: 653
Joined: Wed Sep 21, 2005 3:01 pm

Re: commit messages

Post by code reader »

Acyd Burn wrote:I think the problem code reader points to are those developers face too from time to time... finding out where and when something got changed years ago. ;)
in a nutshell.
true, one can theoretically use "svn annotate".
however, this is less than satisfactory, and has many problems: first and foremost, annotate reports changes on a line-basis rather than logical content basis which in many cases is not what you need.
second, any change to a line, including change in spacing destroys the value of "annotate". a good example is huge sweeps across the project that clean sloppy CRLF-contaminated commits, or any automatic reformatting done to accommodate coding guidelines (convert spaces to tabs, and whoopsy! "annotate" goes out the window).

a well thought-of commit message standard can become very valuable, and create, in effect, a good changelog.
personally, i don't find bug# to be good enough even for bugfixes. i do include the bug#, and if you can automate link-creation it's even better, but i, personally, pay the 1.42 seconds it takes to cun'n'paste the bug description into the commit message, and whenever practical add a few words describing the fix ("initialize $foo to 'bar' " or, "declare $foo global in bar()").
more interesting are commits that deal with new development. personally, i found that good commit messages are invaluable, and help all project participants. in an OS project there is an added value for outsiders (aka "community members"), and it helps us track the project progress and direction.
Highway of Life wrote:What benefit would a project wide standard on commit messages have? :? I’m genuinely curious because to me, a commit message is nothing more than a very simple summary of the commit unless it was a security or bug fix, in which case it would simply be #xxxx
basically, twisi, your question boils down to "what value do commit messages have". it clears (to me at least) that free-form commit messages can work well only for a single-developer projects.
with multi-developer projects, you either set a (somewhat) standard form, or you discard commit messages as a tracking tool. if you choose the latter, you might just as well use empty commit messages altogether (easy enough: svn ci -m "").
undeniably, free form commit messages can also carry some entertainment value (http://code.phpbb.com/repositories/revision/5?rev=8726 ), but it is my experience that they can have more value than that, (and still retain the potential for entertainment value: nobody wants to drain the fun out of developing. that's not the point)
you can see other projects discussion of this issue., e.g. http://markmail.org/message/jba6wkzxwgt73yxy ,
http://drupal.org/node/52287 and http://wiki.fluidproject.org/display/fl ... +Standards (completely random examples)

i don't want to make a huge deal out of it. i started this thread because of several recent "merge" commit messages, and i wanted to ask the merger to copy the original message, as to make the log more readable. i expressed my opinion that a standard would be a bonus, created a snafu by picking on david, and in general made waves.
as i said more than once, it's your sandbox, and you play in it any way you see fit.
peace.
Post Reply