JIRA QuickBuild Plugin

Pull builds from build automation system, feed into JIRA as released versions (or release the version if it already exists), and associate them with eligible resolved issues through issue field Fix Versions.

Description/Features

This plugin pull builds from build automation system, feed into JIRA as released versions (or release an existing version), and associate them with eligible resolved issues through issue field Fix Versions. It can:

1. Periodically polls QuickBuild configurations to get information about latest successful build, and creates/releases corresponding version in related JIRA projects.
2. At the time a version was created and released in JIRA, all issues satisfying below conditions will be associated with this version through the Fix Versions field:
   • Last resolution date of the issue is before repository timestamp of this build.
   • Last resolution date of the issue is after repository timestamp of last successful build in the same configuration.

     NOTE Repository timestamp means repository timestamp of the source code used to construct particular build. For normal build, it is start date of the build; for promoted build, it is start date of the promotion source.

     NOTE This feature will be referenced as "issue association" later.

3. Automatically creates a custom field Download Links, which is used to display build artifact links of related versions for a particular issue. 
4. Issue association can be done for each promotion level independently if configurations of multiple promotion levels are mapped to the same JIRA project.
5. Issue association can be done for each branch correctly if configurations of multiple branches are mapped to the same JIRA project.

Benefits

1. For developers: When fixes issues, developer will never worry about which build contains his fix. He just need to check in code first, then resolve related issues in JIRA. This plugin will pick up a good build from build automation system which is produced after the checkin; add it as a released version in JIRA (or release the version if it already exists), and associate the resolved issues with this version through the Fix Versions field.
2. For QAs: When receives a new build for testing, QA browses change log of the corresponding version in JIRA to get list of issues which has been resolved in this build and is waiting for verification.
3. For release engineers: When release versions, release engineer just need to promote a golden QA build as the release build at QuickBuild side, and this plugin will automatically release the corresponding scheduled version in JIRA.
4. For issue watchers: When watched issues have been resolved, they can easily know which build they are fixed in, and follow Download Links to download that build.
5. For project managers: Reduces management overheads for each project iteration by automatically calculating fixed issues for each iterated build.

A Simple Demo

To get an immediate impression of how this plugin works, just do the following:

1. Visit http://jira.pmease.com and login as user guest, password is guest.
2. Under project TestProjectA, select some open issues, and resolve them (if there are no open issues, you can create some under this project first). Just leave the Fix Versions field as it is when you create or resolve the issues.
3. Visit the QuickBuild demo site, and trigger build for configuration root.JIRA-integration.projectA.QA. (by clicking the gear icon at right side of the screen).
4. Make sure the build succeeds. After one or two minutes, switch to Change Log screen of TestProjectA at JIRA side, and you'll find the newly generated build associated with the list of issues you just resolved.
5. A custom field Download Links is created for these issues to display artifact download links of the Affects Versions and Fix Versions.

Installation

1. Make sure system clock of QuickBuild server and JIRA server are in sync (a slight difference within 10 seconds is acceptable) as this plugin relies on system clock comparison between them.
2. Extract quickbuild-plugin-1.2.1.zip, copy all jar files in the jar directory into JIRA's WEB-INF/lib directory (also make sure to remove old version of these jars in this directory if there is any).
3. Restart JIRA.
4. Login to JIRA as administrator, switch to Administration menu, and click on the Services link under System category.
5. Add a service named by for example quickbuild integrator. Set the service class as com.atlassian.jira.plugin.quickbuild.VersionPuller, and choose an appropriate delay time, for example 5 minutes.
6. Click on Add service button to bring up the service parameter setup screen. The following service parameters need to be set up:
   • QuickBuild URL: This parameter represents URL to QuickBuild instance, for example, http://buildserver:8080/app.do
   • User name: This parameter represents a QuickBuild user which will be authenticated upon version polling. If not specified, anonymous user will be assumed.
   • Password: This parameter represents password of the above user.
   • Configuration to project mapping: This parameter maps QuickBuild configuration to JIRA project key. For example:

     root.projectA.QA : PRJA
     root.projectB.QA : PRJB
     

     This mapping means that for each successful build in configuration root.projectA.QA, a corresponding version will be created and released for JIRA project PRJA; and similarly, each succcessful build in configuration root.projectB.QA will result in a corresponding released version in JIRA project PRJB. Also the Fix Versions property of particular issues will be updated to reflect these newly created/released versions.

7. The installation is done! Do the following to verify if the plugin works:
   • Assume that you've configured the mapping as described in step 5. Create an issue for JIRA project PRJA.
   • Resolve this issue with Fix Versions untouched.
   • Trigger a forced build of configuration root.projectA.QA at QuickBuild side. Make sure the build succeeds.
   • Wait for some time (depends on the service delay time you set above), the newly built version should appear on the "Change Log" screen of JIRA project PRJA, and the newly resolved issue will be listed under this version. Click this issue, and you'll see the Download Links field displaying artifact download links for versions associated with this issue.

Working with multiple promotion levels

You can map configurations of different promotion levels to a single JIRA project and this plugin will be able to do issue association for each promotion level independently. We will use an experiment to help you understand how this plugin handles this case. This experiment uses configuration root.JIRA-integration.projectA.QA and root.JIRA-integration.projectA.Release at http://livedemo.pmease.com:8081.  They represent two promotion levels, and both of them are mapped to project TestProjectA at http://jira.pmease.com. Please follow below steps to accomplish this experiment:

1. Visit http://jira.pmease.com, and login as user guest, password is guest.
2. Create five issues under project TestProjectA for testing purpose. Suppose they are feature1, feature2, feature3, feature4, and feature5.
3. Resolve feature1, and then force a build for configuration root.JIRA-integration.projectA.QA at http://livedemo.pmease.com:8081. Suppose the newly generated build is projectA-1.1 QA#1 (The actual versions generated by QuickBuild online demo may be different from this and later versions, but the mechanism is the same).
4. Wait for one minute, and examine Change Log screen of JIRA project TestProjectA. The version named projectA-1.1 QA#1 is expected to be there containing issue feature1 (it may also contain other issues which are created and resolved by other users before this version is built).
5. Repeat step 3 and 4 to resolve feature2 and force build in configuration root.JIRA-integration.projectA.QA. Version projectA-1.1 QA#2 is expected in the Change Log screen to contain feature2.
6. Till now you can find that for each QA build, a corresponding QA version is created and released in JIRA. In the real world, when a tester receives a new QA build for testing, he can open the Change Log screen to see what issues are resolved for this build, so that he can verify against these issues.
7. Now you decide that projectA-1.1 QA#1 is the golden QA build and should be promoted as the formal release version. To do the promotion, open this build at QuickBuild side, and click the Promote button. This will result in promoted version projectA-1.1 in root.JIRA-integration.projectA.Release.
8. Wait for one minute after the promotion, the version projectA-1.1 will appear in Change Log screen of JIRA project TestProjectA. This version contains feature1 but not feature2 as it is promoted from projectA-1.1 QA#1 and its repository timestamp is before resolution date of feature2.
9. Repeat step 3 and 4 to resolve feature3 and force build in configuration root.JIRA-integration.projectA.QA. Version projectA-1.2 QA#1 is expected in the Change Log screen to contain feature3.
10. Repeat step 3 and 4 to resolve feature4 and force build in configuration root.JIRA-integration.projectA.QA. Version projectA-1.2 QA#2 is expected in the Change Log screen to contain feature4.
11. Now you decide to release projectA-1.2 and the promotion is done at QuickBuild side from build projectA-1.2 QA#2.
12. Again, wait for one minute after the promotion, the version projectA-1.2 will appear in Change Log screen of JIRA project TestProjectA. Based on step 8, you may guess that this version should only contains feature4 as it is promoted from projectA-1.2 QA#2. However this is not true. Version projectA-1.2 contains not only feature4, but also feature3 and feature2. The reason is that issue association is performed for each configuration independently (as if other configurations does not exist). Let's look again at the issue association conditions:
    • Last resolution date of the issue is before repository timestamp of this build. In this case, repository timestamp of this build is start date of build projectA-1.2 QA#2 as it is the promotion source of build projectA-1.2.
    • Last resolution date of the issue is after repository timestamp of last successful build in the same configuration. In this case, last successful build in configuration root.JIRA-integration.projectA.QA is projectA-1.1 which is promoted from build projectA-1.1 QA#1. So the repository timestamp of last successful build here is start date of projectA-1.1 QA#1.
    • This explains why feature2, feature3, and feature4 are included in version projectA-1.2.

Working with multiple branches

Serious projects often have multiple branches in development at the same time. For example, while your team is working hard on the main branch towarding the great 2.0 release, 1.0 branch still needs to be maintained for existing customers in order to fix urgent bugs. In case of a multi-branch environment, unless you create separate JIRA project for each branch (which is too complicated), the auto-association between issue and version will facing a big problem just using the issue association conditions mentioned earlier. To describe the problem, let's assume this mapping:

root.myproject."1.x".QA: MYPRJ
root.myproject.main.QA: MYPRJ

QA configuration from two branches (1.x and main branch) are mapped to a single JIRA project keyed by MYPRJ. Suppose there is an issue feature1 which is only valid for 2.x branch. After several days' hard working, jacky put source code of feature1 into main branch of the version control system, and mark this feature as resolved in JIRA. After this, a build for example myproject-2.0 QA#5 may get generated in configuration configuration root.myproject.main.QA and it will be pulled into JIRA to associate with feature1 which is perfect. However, another build myproject-1.3 QA#8 may get generated in configuration root.myproject."1.x".QA and it will be pulled into JIRA and associated with feature1 in the same way. And this is definitely not we want.
In order to overcome this problem, we need to find a way to determine the set of valid configurations for a particular resolved issue. A special variable with the name futureversion_verification_expression (refer to Special variables appendix of QuickBuild's user guide) is just designed for this purpose. The algorithm to determine if a particular configuration is valid for a particular issue is described as below:

1. If variable futureversion_verification_expression can not be found in current and ancestor configurations, the configuration is considered to be valid for the issue.
2. If variable futureversion_verification_expression can be found in current or ancestor configurations, for each unreleased fix version of the issue, the version name is passed to current configuration as futureVersion property, and variable futureversion_verification_expression will be evaluated as an OGNL boolean expression. If any of the existing fix version leads to a true evaluation of the expression, the configuration is considered to be valid for the issue; otherwise, the configuration is not valid for the issue and will not be associated with the issue although the [issue association conditions|#issue_association_conditions] are met.

We'll use an experiment to demonstrate this algorithem:

1. Visit http://jira.pmease.com, and login as user guest, password is guest. The JIRA project TestProjectB is pre-configured with below mapping:

   root.JIRA-integration.projectB."1.x".QA: TSTB
   root.JIRA-integration.projectB."1.x".Release: TSTB
   root.JIRA-integration.projectB.main.QA: TSTB
   root.JIRA-integration.projectB.main.Release: TSTB
   

2. Create an issue under TestProjectB, for example feature1. Suppose this feature is only needed for branch 1.x, so let's schedule it to be fixed in 1.x series by setting the Fix Versions as projectB-1.x.
3. Create an issue under TestProjectB, for example feature2. Suppose this feature is only valid for the main branch, and we schedule it to be fixed in the up coming 2.0 release by setting the Fix Versions as projectB-2.0.
4. Create an issue under TestProjectB, for example bug1. Suppose this bug should be fixed both in 1.x and main branch. So we set the Fix Versions as projectB-1.x and projectB-2.0.
5. Resolve feature1, feature2 and bug1 with Fix Versions untouched.
6. Visit http://livedemo.pmease.com:8081, and force build in configuration root.JIRA-integration.projectB."1.x".QA and root.JIRA-integration.projectB.main.QA. Suppose the new builds generated are projectB-1.5 QA#8 and projectB-2.0 QA#3 (The actual version name may be different, but the theory is the same).
7. Wait for one minute after the build, the newly generated builds in step 6 shoud appear in Change Log screen of TestProjectB. Issues associated with projectB-1.5 QA#8 is feature1 and bug1 (may contain issues resolved by other users), while issues associated with projectB-2.0 QA#3 is feature2 and bug1 (may also contain issues resolved by other users). This is perfectly correct, but how does this happen? The answer is the variable futureversion_verification_expression defined in configuration root.JIRA-integration.projectB."1.x", and root.JIRA-integration.projectB.main:
   • Change to Basic settings tab of configuration root.JIRA-integration.projectB."1.x"; you'll find the variable futureversion_verification_expression is defined there with the value futureVersion.startsWith("projectB-1."), and it will be inherited by its child configurations root.JIRA-integration.projectB."1.x".QA and root.JIRA-integration.projectB."1.x".Release.
   • Change to Basic settings tab of configuration root.JIRA-integration.projectB.main; you'll find the variable futureversion_verification_expression is defined there with the value futureVersion.startsWith("projectB-2."), and it will be inherited by its child configurations root.JIRA-integration.projectB.main.QA and root.JIRA-integration.projectB.main.Release.
   • As Fix Versions of issue feature1 and bug1 contains the unreleased version projectB-1.x, and the expression futureVersion.startsWith("projectB-1.") is evaluated to true if futureVersion is replaced by projectB-1.x, so the configuration root.JIRA-integration.projectB."1.x".QA is valid for feature1 and bug1. However, no unreleased fix version of issue feature2 can satisfy this expression, so this configuration is not valid for feature2.
   • For the same reason, configuration root.JIRA-integration.projectB.main.QA is valid for issue feature2 and bug1, but not feature1.

Working with the carryover version

Still we'll use an example to help you understand the carryover version:

1. Suppose you are mapping configuration root.myproject.QA and root.myproject.Release to JIRA project myproject (keyed by MYPRJ) as below:

   root.myproject.QA: MYPRJ
   root.myproject.Release: MYPRJ
   

2. Create a unreleased version for myproject in JIRA. Assume the created version is myproject-2.0.
3. Create an issue under myproject in JIRA, and choose myproject-2.0 as its Fix Versions. Assume the created issue is feature1.
4. At QuickBuild side, force a build in configuration root.myproject.QA. Suppose the newly generated successful build is myproject-2.0 QA#5.
5. Wait for some time (depending on the service period you configured for QuickBuild plugin) until version myproject-2.0 QA#5 appears in JIRA.
6. Resolve feature1 in JIRA.
7. Promote build myproject-2.0 QA#5 into configuration root.myproject.Release as build myproject-2.0.
8. Wait for some time until version myproject-2.0 is set to released in JIRA. A unreleased carry over version myproject-2.0.carryover will be created automatically, and Fix Versions field of issue feature1 will contain this carry over version.

Thinking a little over above steps, you'll find that resolution date of feature1 is after repository timestamp of myproject-2.0 which is promoted from myproject-2.0 QA#5. Based on this, QuickBuild plugin thinks feature1 is actually not resolved in myproject-2.0, and it removes myproject-2.0 from Fix Versions field of feature1 when myproject-2.0 is set to released in JIRA. However, as feature1 is scheduled into myproject-2.0 by the user, the removal action will disturb the schedule. So QuickBuild plugin creates an unreleased version myproject-2.0.carryover holding all questionable issues for tracibility, and the user can select to batchly re-schedule these issues into next version.

Build From Source

Although this plugin integrates with QuickBuild, you can easily modify the source to connect to other build automation systems. To build from source:

1. Make sure Apache Ant 1.6.x (or higher) and JDK 1.5 (or higher) is installed.
2. Download the source distribution of this plugin, and extract it under a directory, say, d:\quickbuild-plugin-1.2.1-src.
3. Modify file d:\quickbuild-plugin-1.2.1-src\build.xml, and change value of the property jira.standalone.dir to be the installation directory of JIRA standalone edition (version 3.5 or higher).
4. Open a command prompt; change to directory d:\quickbuild-plugin-1.2.1-src, and run command ant to build this plugin.
5. If build successfully, the binary distribution file will be placed into directory d:\quickbuild-plugin-1.2.1-src\distribute.