Subversion - Roundup Integration Project

Author: Richard Jones
Date: August 27, 2007

This file documents the work undertaken for Chris Ryland @emsoftware.com for the purposes of integrating Roundup and Subversion.

Contents

Goals

This project will integrate Subversion and Roundup, with the following goals:

  1. Commits to a Subversion repository should be able to optionally attach the commit message to a Roundup issue and further be able to affect the issue's status.
  2. Within Roundup, the Subversion commit information (log message, revision number) will be stored and displayed usefully.
  3. Roundup's web interface will provide a link to revision information, either directly or linking back into the Subversion repository in the form of a 3rd-party web interface.

Implementation Plan

The integration will take the form of two components:

  1. Communicating from Subversion (messages to Roundup)
  2. Data handling in Roundup to support references to Subversion

Communicating from Subversion

Information needs to be passed to Roundup from Subversion when a commit takes place. This will be handled by the script notify-roundup.py

Determining Roundup Information

The trigger for talking to Roundup will be a token in the change log message formatted on a new line as:

<issue designator> [<new status>]

for example:

issue3
issue123 resolved
issue12 done-cbb

The information required to work with Roundup will include:

  1. the change message as generated by mailer.py,
  2. the (host, path) of the repository generating the message,
  3. the svn revision number,
  4. the issue number to affect, and
  5. any change to make to the status of the issue.

Direct Communication

A hook script that directly accesses a Roundup tracker will be able to use the Roundup API to create new revisions, messages and modify issues according to the information extracted from the change log message.

Email Communication

In this scenario, information is passed to Roundup using the standard mail gateway. The message will be crafted to have a Subject: line:

[<designator>] SVN commit message [status=<new status>]

An auditor on the Roundup side parses the incoming message to extract the repository (host, path) and the revision number.

To determine the author of the change message, the Subversion username must be translated into an email address that your tracker may identify. The simplest method of doing this is to append an email domain, thus creating "<username>@<email-domain>". This domain is configured using the "email :: default-domain" variable in the configuration file.

If some Subversion users don't have convenient email addresses like this, then you may specify either just the name part or their whole address in the configuration file. See the "address mappings" configuration file description below.

Configuration

The script notify-roundup.py implements both a "local" and "email" mode of operation, controlled by a configuration file (see notify-roundup.ini for a sample configuration).

Data Handling In Roundup

Information needs to be handled, stored and presented to the user. A single Link to a Subversion revision will appear on each message, which is obviously optional. It is automatically set by the Subversion hook script notify-roundup.py

We will want to formally store Subversion revision numbers relevant to an issue. These will then be used to format links from the issue to a Subversion web interface which may view information about the revision.

Deliverables

All deliverables will be made publicly available.

  1. This document.
  2. Documentation and support files enabling anyone to implement the Subversion integration.
  3. A modified 0.8.2 "classic" tracker template with the modifications in place.

Accompanying Files:

svn-integration.html
Documents how to set up the Subversion integration.
svn-tracker-1.5.zip
Ready to go template to create a Subversion-linked Roundup tracker. Run roundup-admin install in the directory created by the zip file.
notify-roundup.py
Subversion hook script. Is placed in the repository's "hooks" directory.
notify-roundup.ini
Sample configuration file for notify-roundup.py. May be placed anywhere, as the location of this file is the first argument to the notify-roundup.py script.
svnauditor.py
Auditor handling incoming notification messages. Goes in the tracker "detectors" director, and is only required if the email mode of notify-roundup.py is used.
svn_rev.item.html
Tracker HTML template allowing display of revision information. Goes in the tracker "html" directory.
revision_info.py
Support code for the revision information display - goes in the tracker "extensions" directory.

Change History

2007-08-27 - 1.5

  • Fixed svn_repo permission advice.

2004-04-31 - 1.4

  • Document permission assignments required to create svn_rev items

2005-04-27 - 1.3

  • Fixed suggested formatting of viewcvs_url to format as integer
  • Fixed traceback in notify-roundup.py

2005-05-16 - 1.2

  • Status wasn't being set by ID in local mode
  • Wasn't catching errors in local changes, hence not cleaning up db correctly
  • svnauditor.py wasn't handling the fifth argument from notify-roundup.py
  • viewcvs_url formatting wasn't quite right

2005-05-04 - 1.1

  • Several fixes from Ron Alford
  • Don't change issue titles to "SVN commit message..."

2005-04-26 - 1.0

  • Initial version released