Integrating with Mercurial

Mercurial is a Distributed Version Control System (DVCS) system that keeps track of software revisions and allows many developers to work on a given project without necessarily being connected to a common network since it doesn't rely on a central repository, but instead distributes copies of the entire source code repository to each user's workstation.

The SpiraTeam plug-in for Mercurial allows users of SpiraPlan or SpiraTeam (hereafter referred to as SpiraTeam) to be able to browse a Mercurial repository and view revisions linked to SpiraTeam artifacts.

The plug-in will download a read-only working-copy of the Mercurial repository onto the SpiraTeam server and use that for displaying the list of files/folders. The list of revisions will be queried dynamically from this local repository on an as-needed basis. The plug-in also performs 'pull' requests from the specified remote repository to ensure that the local repository remains up to date.

The rest of this section outlines how to install and use the plug-in with SpiraTeam.

Note: The plug-in will allow users to download and view different revisions of files and view revision logs, but no changes to the repository are allowed through the plug-in.

Installing the Mercurial Plug-In To install the Mercurial Version Control plug-in, follow these steps:

Using Mercurial with SpiraTeam

While being able to browse the source code repository can be useful in itself, the real strength comes from linking artifacts in SpiraTeam - including Incidents, Requirements, and Tasks - to revisions checked into the software repository.

Viewing the Repository Tree

View the source code tree by selecting the "Source Code" link under the Tracking tab. You will get a screen similar to:

The folder tree of the repository is on the left, and files in the current selected directory will be listed in the right table. Note that this view will always show the current (TIP) branch of the repository. The file view will display the filename, the current revision number of the file and the date of the last commit. You can filter and sort on any of the columns, as well.

Viewing File Details

To view the file details, click on a file in the right-hand side of the repository. The file details page displays the details on the selected revision. By default, it will be the TIP branch, unless you clicked to view the file details from a revision. By clicking on the file name, you can download the specified revision of the file to your local machine. This does not do a Mercurial clone or pull; you are merely downloading the file to your local machine.

Underneath the file details is a list of all the revisions (Mercurial changesets) that this file belongs in, or was committed to, who performed the commit, and the log message for the commit. Throughout SpiraTeam, revisions are indicated by the Revision


Revision Details

By clicking on a revision in SpiraTeam, you will be taken to the revision details page.

The revision details screen shows the log for the changeset, the commit date and author. At the bottom of the page are two tabs, Files and Associations. The Files tab lists all files that were a part of this commit, with their full path, size, latest revision and date of edit.

The Associations tab shows any artifact (Incident, Requirement, Test Case, Test Set) that the log message references. See Linking Artifacts for information on how to link a revision with a Mercurial changeset:

Linking Artifacts

Linking an artifact is quite simple. To maintain the readability of Mercurial changeset messages, we adopted a square bracket token. The token is in the format of:

[<artifact identifier>:<artifact id>]

The first half, the Artifact Identifier, is a two-letter code that is used throughout SpiraTeam, and is visible on almost every page in the application. For example, a requirement's identifier is "RQ". Incidents are "IN", and test cases are "TC". The artifact ID is the number of the artifact. So by creating a commit message that reads:

SpiraTeam will automatically detect tokens and will include links to them under the Associations tab for a revision detail.


While integration with Mercurial is sophisticated behind the scenes, as a user you will only receive a couple of errors that will prevent the integration from working:

Data Purging

Since the integration with Mercurial requires that a working copy of the Mercurial repository be stored on the SpiraTeam server, you may decide at some point to unlink a disused Mercurial repository from SpiraTeam to save disk-space. However unlinking the repository through the SpiraTeam web interface will not remove the working copy of the repository from the server.

To permanently remove a repository from the SpiraTeam server, you need to locate the following path:

If you look inside this folder, you will see a subfolder called "Inflectra", and under that will be a subfolder called "MercurialProvider". If you open up this subfolder, you will see a list of all the Mercurial repositories that have been accessed through SpiraTeam. To purge a module, just select it and choose the Delete Folder option in Windows.