Comments on: Version Control Check-In Comments

By: Mark Phippard

Mark Phippard — Thu, 22 May 2008 20:28:06 +0000

This blog post by one of the Subversion developers is a good read:

http://blogs.open.collab.net/s.....sion_.html

By: Jim

Jim — Thu, 22 May 2008 19:03:44 +0000

FYI – I updated this and added a few links I found – one regarding some tips and tricks with the Subclipse commit dialog window and the other regarding integrating SVN and bug trackers.

By: Rob Wilkerson

Rob Wilkerson — Thu, 22 May 2008 15:26:31 +0000

Using Trac+Svn, I ask my developers to focus their comments around _why_ a change was made. Trac’s diff does a nice job of visualizing _what_ was changed. Similarly, we use Trac’s post-commit hook for Svn, so my entire comment syntax might look like:

(Fixes|Addresses|Re #3902.)? One sentence indicating _what_ was changed. Then as much content as needed – a sentence or a short novel – about why the change was made.

I like to be able to look at the timeline and see, at a glance, what changes were made and why so that I can see if I want to take a closer look at anything. This comment structure allows me to do that.

By: shag

shag — Thu, 22 May 2008 01:42:39 +0000

i find this funny. when i wasn’t using version control years back, i commented my code the exact same way and added a date. since i’ve been using svn, i just type my comments, which usually have updated, deleted or created in them.. hmmm.. i think i need to go back to my previous practice. i wish we could add a label/category. that would be even better in my opinion.

By: Fernando Lopez

Fernando Lopez — Thu, 22 May 2008 00:26:10 +0000

We use CVS and we have no standar. Enter as much as you can is the norm.
I personally hate when some of the developers just enter a Ticket# or a link on the Check-IN comments. That means I have to go open another window copy/paste the ticket number and go through the “why they needed/wanted something changed” to figure out the “what changed in the code”.

I normally enter a description explaining what changed and in some cases point the line number where I changed things.
Something like
“Added new column [LastContact_date ] to the CFQUERY getCustomers. Line 254″.

I also enter the Ticket # and a link if there’s one.

The idea of entering ADDED/FIXED/DELETED makes a lot of sense. I think I’ll start implementing it as soon as tomorrow morning.

Thanks for the tip.

By: Brian Kotek

Brian Kotek — Thu, 22 May 2008 00:19:28 +0000

I follow a similar convention. I give a quick summary of what is changed in the revision, and we use Trac’s SVN link to allow for automatic association and closing of Trac tickets through SVN comments. So something like this:

Added salting and SHA-512 hashing to user passwords. Fixes #148

will automatically close Trac ticket #148 (and add a comment to the Trac ticket referencing the SVN revision in which it was fixed/added). This combo is pretty killer, and when using Mylyn to interact with Trac from within Eclipse, you close the circle completely.

By: Steve Brownlee

Steve Brownlee — Wed, 21 May 2008 20:15:23 +0000

@Barney: I disagree, but that’s ok ;)

By: Barney

Barney — Wed, 21 May 2008 20:08:54 +0000

Steven,

Doing that makes your version control log nearly useless. IDEs are getting better about integrating with ticket systems (e.g. Mylyn for Eclipse), but they still end up fronting version control directly in most cases. Having an log message with no details about what happened in the commit makes that basically useless. Version control should contain the “how”, and the ticket system should contain the “what” and “why”. All three parts are important.

By: Steven Brownlee

Steven Brownlee — Wed, 21 May 2008 19:40:55 +0000

I always use a ticket tracking system, so when I commit, I simply enter in the following template:

{Task #} : {Task Name}
{URL to task}

By: Barney

Barney — Wed, 21 May 2008 19:36:01 +0000

We use Trac with our SVN, so our commit messages have adopted some of Trac’s markup. In particular, starting a line with ” * ” (that’s space, asterisk, space) makes for nice lists of changes, and converts to UL/LI within Trac. So a “typical” commit message might be something like this:

re #123:
* added x to do a
* changed y to do c instead of b
re @456:
* deleted z

This ends up with very readable commit messages both in Subversion and in Trac. The @ sign is used for ticket references for @task (another ticketing system we use). We’ve written a plugin for Trac that will convert such strings into links to the @task tickets just like Trac does for Trac tickets natively.