Thursday, July 16, 2009

Linking checkins to tickets (SDI 07 VII)

There are two crucial pieces information related to every change to the project's codebase: the what and the why.

Thanks to using svn for version control, all the details regarding what a change is are being automatically recorded in the form of an atomic changeset which moves the codebase from one (hopefully) consistent state to another.

Recording the why requires a bit more work. In this simple workflow, we are using Track tickets to document and track every single legitimate reason for making a change to the codebase - whether they are bugfixes or work items related to new features or enhancements. If every legitimate reason to change the code is represented by a ticket, then for each svn changeset there should be one or more tickets which shows why this change was made. Code changes shoudl be done in small incremental steps, but the reason for these changes may be a fairly large an complicated project requiring many small code changes. Tickets can also be used as threads for resolving and documenting design decisions.

In the Trac web interface any reference to other Trac "objects" like svn changesets, tickets or wiki entries are automatically represented as hyperlinks. In order to link a svn changeset to its related tickets, all we need to do is to mention "#<tktnum>" in the commit message for this change. In order to automate the reverse linkage from the ticket to the changesets which refer to it, Trac provides an optional script which can be installed as a svn pre-commit hook to post a message to the ticket log with the changeset ID.

There are two scripts which can be downloaded from http://trac.edgewall.org/browser/branches/0.10-stable/contrib/ or whatever version of Trac is being used. The first one is trac-pre-commit-hook which can be used to automatically enforce the policy that each svn changeset message must contain a reference to an open Track ticket number in the form of expressions like ”closes #5”, ”fixes #34”, ”addresses #456” or ”references #4”.

The second one is trace-post-commit-hook, which will post messages to the corresponding tickets referenced this way in the commit message after the commit has been successful and potentially changes the state of the ticket in the case of "closes" or "fixes" references.

In order to install one or both of these hooks we need to create the following /data/sdi07/svn/hooks/pre-commit script:
#!/bin/sh

REPOS="$1"
TXN="$2"
TRAC_ENV="/data/sdi07/trac"
LOG=‘/usr/bin/svnlook log -t "$TXN" "$REPOS"‘
/usr/bin/python /data/sdi07/svn/hooks/trac-pre-commit-hook \
"$TRAC_ENV" "$LOG" || exit 1
exit 0
and add the following to the already existing /data/sdi07/svn/hooks/post-commit script:
/usr/bin/python /data/sdi07/svn/hooks/trac-post-commit-hook \
-p /data/sdi07/trac/ -r "$REV" -s "sdi.kugelfish.com/sdi07/trac/"