Hopefully everyone is now using some form of version control these days… I’m curious how you comment your check-ins? I found this interesting post: Subversion Check-in Comment – Great Practices where the author suggests labeling your changes with the following categories:
Added,Changed,Fixed,Deleted
So your comment would look like:
ADDED: I added a new form to the checkout process.
FIXED: I fixed Bug #12345 (link to ticket system).
DELETED: Banner image from header.
I’ve been doing something similar myself and was curious what others are doing? I poke around some open-source projects occasionally and don’t really find any consistent standard. Some people dump tons of information, some none at all. What do you do?
Update: This post by Features of the Subclipse Commit Dialog has some great tips about the commit dialog in Subclipse. I’m tinkering around with setting up a comment template now… He also has a good one about regarding bug tracking integration here: Integrating Subversion with your Issue Tracking System
@Jim
Wow, I’ve been using Subversion for years now, and am usually pretty good at entering comments on checkin. Really like the idea here to start with those keywords, makes tons of sense. Thanks for the heads up…
At my current job. we add change comments at the top of every file, as well as in our source control system. They usually describe what was changed and for what bug or feature.
But, :)
Years ago I worked for a major travel company and had a series of very late nights at the office to convert thousands of templates from table/font layout to CSS. CVS was setup to require comments on check-in and we developers were told that “no one outside of our group looks at those comments”. I got so slap happy at one point, I just started entering all kinds of things to pass the time.
A few weeks later, QA sent me a thank you e-mail. They’d never seen anyone document changes in Pokemon before. (100s of entries read to the effect of “Pika, Pika. Pika pika pika-chu!”)
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.
I always use a ticket tracking system, so when I commit, I simply enter in the following template:
{Task #} : {Task Name}
{URL to task}
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.
@Barney: I disagree, but that’s ok ;)
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.
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.
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.
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.
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.
This blog post by one of the Subversion developers is a good read:
http://blogs.open.collab.net/svn/2007/05/the_subversion_.html