Apr 09
Subversion Is Documentation, Too
As I approach the end of a development project, I am becoming more and more aware of worthless documentation. Our dev team made an agreement with our client about the documentation that would be provided when we transition the project. Because of this, I have been examining all of the different documentation being provided and doing my best to strip out the cruft. The latest goldmine of not so helpful comments I have found is version control logs, especially when combined with fix messages on your bug tracking system.
The problem, as I keep saying, is finding any actual value in them. After looking through my team’s latest commits, I spent more time viewing the actual differences in the source than the messages provided alongside. After a few minutes of this, I began to look for the ideal commit message, and finally decided that one does not exist. All of your commits should be tied to a bug/issue/feature in your tracking software, and your messages are better made there. By only writing messages in your tracking software, you will never duplicate the same message in your source control logs. Even better, there are probably more people involved in your development process than just developers and other “code touchers” (one who checks out the code from source control). The non code touchers are very unlikely to see commit messages, and could potentially lose out of some important information tucked away in subversion.
April 6th, 2009 at 12:27 am
I like how there is no easy integration between VersionOne and our source control solutions (At least my team does not use one).
If everyone committed early and often – then we would never need documentation – we could read an RSS feed of diffs and call it good.
April 6th, 2009 at 11:39 pm
Yah i totally agree. We’ve been using Rational Team Concert at work (and in my case, working on it) and it’s been incredible! It’s a great combination between SCM and work item/bug tracking all in one. You commit your changes as a change set and associate them with a specific work item. Users can then track work items, comment, quickly post screen shots, etc. It gives you the power of a bug tracking/work item system and the integration with source control. No longer do you have to worry about those uninformative SVN commit messages.
I thought the idea was cool when i first heard about it, but after 2 months of working with it… I can’t imagine being without it. It’s incredible!
April 9th, 2009 at 12:56 pm
That sounds awesome. SCM and bug tracking should really be one in the same system. I need to check out where Team Concert is now that another six months have gone by.