November 19, 2013

Swarm, Meet Jira. Jira, Meet Swarm

Helix Swarm
Traceability

Introduction

One of our favorite new features in Swarm 13.2 is the automatic detection and linking of references to JIRA issues made in Perforce changelist, review and job descriptions. Comments made in Swarm on any of these objects will also automatically create links back to the JIRA issues.

This new form of JIRA integration supplements an earlier, more comprehensive integration between Perforce Jobs and JIRA, called the Perforce Defect Tracking Gateway (P4DTG). The new Swarm integration is much lighter, and available immediately to use with any of your JIRA projects - which are automatically detected. While Swarm’s integration to JIRA is sufficient for most needs, if any level of data synchronization between Perforce Jobs and JIRA tickets is desired, then P4DTG does provide this enhanced experience.

Because the links are created for you between JIRA and Swarm, when you browse your JIRA issues you can go directly to submitted code or code diffs. This enables quicker access to the social-coding features of Swarm directly from JIRA.

Enabling Jira Integration with Swarm

To enable the JIRA module in Swarm, the Swarm configuration file needs to be modified by your Swarm Administrator (e.g., /data/config.php). The Admin only needs to provide the JIRA hostname URL and the JIRA user account credentials which Swarm uses to access the JIRA 5.x REST interface. The other fields are optional.

Swarm then automatically connects to the JIRA server and gets a list of all JIRA project prefixes. After that, any mention of a JIRA issue in a Perforce Changelist or Review object’s description field, will link that object to the JIRA issue.

For example, suppose you have the issue CORE-1234, where CORE is a valid JIRA project prefix, then just add CORE-1234 to your submit command description:

$ p4 submit –d “CORE-1234: my awesome bug fix.”

Swarm will do the rest. It will contact JIRA and create a LINK field back to the new changelist number assigned to your submit. For added convenience, Swarm will also activate links to all text that matches the JIRA tickets in Swarm so users can link directly back to JIRA with one click.

Note that the JIRA issue mention can appear anywhere in the description, with some minor exceptions. For example, it cannot appear in a URL unless it is the full JIRA issue URL, http://myJira/browse/CORE-1234 in this example. This string is constructed from the JIRA host configuration you put in data/config.php.

Fixing Changelist Comments

Swarm will only append links to your changelists in the JIRA issue during the initial submit. A known limitation at present is that if you edit your changelist description after the initial submit to add the JIRA issue mention, you will need to manually add Swarm links to your JIRA issue in order to have the full round-tripping between Swarm and JIRA. However, Swarm will still activate a link to the JIRA issue when you browse the changelist from Swarm.

Enforcing Jira Processing

If your shop requires a JIRA issue number with every submit, and you have a p4d processing hook to reject submits that do not have a JIRA mention, then you will rarely have to manually fix-up the JIRA-Swarm links. There may be an occasionally typo, for example, when a submitter enters the wrong issue number.

We recommend the approach of enforcing JIRA tickets, especially if you use JIRA for other processing such as Release Notes generation, and need to collect p4 submit data in JIRA as part of your release processing.

Jira, Swarm, and Commons

If you are using Perforce Commons, everything works the same when content contributors add a JIRA issue mention when they upload a document through Perforce Commons.

Jira, Swarm and Git Fusion

If your development team uses Git Fusion, the same rules apply. However, now you have two places where you can enforce JIRA mentions – in a Git repository pre-commit hook, or in a p4d submit hook. I would recommend enforcing at the Git level, since this is the earliest opportunity you have, and it may be a tiresome task to have a Git Fusion push rejected due to missing JIRA mentions. Ideally, you might set up a central Git repository that enforces the commit hooks, and then automate the secondary push to Perforce, once the commit has been sanctioned by the intermediate Git repository.

You also have the option of pre-processing a Git repository you plan to upload to a Git Fusion back-end, to integrate with your JIRA tracking. For example, if you plan to integrate a new external project from Git, and have one or more JIRA issues associated with that work, then just write a script to edit the Git commit comments prior to pushing the Git repository to Git Fusion.

Later, if you pull in a new snapshot of the external project, then once again, you can pre-add JIRA issues prior to the remote push via Git Fusion. This will give you an exact audit record of all changes made from each snapshot as you continue to track the external project.

Summary

Integrating Swarm and JIRA provides a powerful new capability for accessing p4 changelists from the JIRA interface, and accessing JIRA directly from Swarm. This is especially attractive for shops that rely on JIRA to track multiple projects to categorize the daily influx of submits from any source, whether it be through Perforce directly, Swarm, Commons, or Git Fusion.