Time Tracking Mashup: RallyClock API / Subversion

If you are a developer, you probably keep track of your source control commit messages for time tracking purposes. Well if you are using SVN (Subversion) for your source control, here is one nifty way to keep RallyClock informed about what you are doing by appending your commit messages right on to your active RallyClock timer as notes.

Here we will show you how to do this easily using a little Perl code we cooked up and RallyClock’s API. This article goes through it step-by-step.

Required Downloads

First you will need to download a few files that will handle the housekeeping and communication between your SVN repository and RallyClock.

RallyClock.pm

This is the communication library (perl module) that handles all the communications between your svn repository and RallyClock. You need to place this file somewhere in the Perl include path on your server running SVN.You will also need a few prerequisite perl modules XML::Simple and LWP::UserAgent for this module.The good news is, once you download this library, you can do all sorts of RallyClock things with the power of Perl.

rallyclock-update-timer.pl

This is the bootstrap script that uses the library above and will be executed by svn when you commit any code. Save this file into svn repo hooks directory usually located at /var/svn/[your repo]/hooks. Make sure this file has execute permission by the user that svn is running as.

$ cd /path/to/svn/hooks/
$ wget http://blog.rallyclock.com/wp-content/uploads/2007/10/RallyClock.pm
$ wget http://blog.rallyclock.com/wp-content/uploads/2007/10/rallyclock-update-timer.pl
$ chown (svn-user) ./rallyclock-update-timer.pl
$ chown (svn-user) ./RallyClock.pm

Modify/Configure for your Environment

Open rallyclock-update-timer.pl in your favorite text editor. You will need to change two variables in this file:

1. $billing_code needs to be set to the billing code for the project you want svn to communicate to. You can only have one billing code per svn repository. The format for this code is [client account#].[project code] format.
2. $usermap This is a hash that contains a map of your svn username to your RallyClock username and API key. You can have as many as you want. See below.

For $billing_code:

our $billing_code = '1000.09';

For $usernmap:

# This is a map of the SVN user to RallyClock username and API key.
# You can get your RallyClock API key in your profile
# by visiting: http://go.rallyclock.com/profile
$usermap = {
  # Pattern is:
  # SVN user => {user => RallyClock user, key => RallyClock API key}
  jpowers => {user=>'jay', key=>'XXXXXXX'},
  dpfeffer => {user=>'doug', key=>'XXXXXXXXX'},
  bkaney => {user=>'bkaney', key=>'XXXXXXXXX'},
};

Testing Before Integrating to SVN

Let’s test the perl-side of things before implementing to SVN to make sure things are working okay. First, start a timer for the project we will be sending SVN messages to. You can do this from the web or IM.

Then lets run some test code that simulates an actual SVN commit.

$ /usr/bin/perl rallyclock-update-timer.pl -a jpowers \
          -c 99 -m "this is a test commit message"

In this case we have -a is the author, -c is the changeset and -m is the SVN message. After running this command, check out your timer to make sure your test message was appended.

Integrating to SVN using HOOKS

To execute the RallyClock code when an svn commit occurs you need to edit the post-commit file in your svn root directory. Below is what you should place at the bottom of this file. You will see it pretty much matches the test code we ran above.

$REPOS/hooks/rallyclock-update-timer.pl -a $AUTHOR -c \
          $REV -r $REPOS -f "$FILES" -m "$MESSAGE"

Bask in the Automation!

And that’s it. Now if you have a timer going for the project, your SVN commit messages will auto-magically get appended to your timer. So now you can:

1. Start work, fire off a RallyClock Timer.
2. Figure out the issue that was causing that unit test to fail, run svn commit -m "Fixed the distribution failure, wrong assumption in fixture."
3. Finish your timer without having to go back and fill in the notes from your SVN commit log!