Jira and Jira Align Integration: Release Vehicle/Fix Version Best Practices

[#1]

Before integrating Jira with Jira Align, there are some best practices that should be considered. Some are a little more rigid than others; while others can lend themselves to some workarounds. Let's explore further to understand what these are, why these are important and the potential impacts. 

Caution of syncing release vehicles/fix versions

Fix versions in Jira are created by project and could potentially create duplicate release vehicles in Jira Align that represent the same release.

Why: When using 1 project to 1 board structure, each project has its own fix version that could be duplicated over projects. All of these fix versions will sync over to Jira Align as individual release vehicles.

Workaround: Grouping release vehicles in Jira Align is an option but will not solve this as all of the fix versions will still be created as individual release vehicles in Jira Align.

Assigning releases to features

If wanting to assign releases to features, release vehicles would need to be created in Jira Align and fix versions would need to be created in Jira. In turn, these should not be synced with each other and would need to be maintained manually.

Why: The recommendation is to not sync release vehicles in Jira Align and fix versions in Jira. Due to this, if there is a need/desire to track work by release, it would need to be maintained manually.

Integration behaviors to be aware of

If the Fixed Version sync between Jira and Jira Align is enabled in the Jira connector settings:

• A release vehicle will be created for each project the fixed version has been assigned to even if it is the same name
• In Jira Align, if different features from different programs (aka Jira projects) are added to the same release vehicle, it won't sync because you can't have 2 projects tied to the same release vehicle. It must be unique.

---

Related Articles

• Jira and Jira Align Integration: Sprint Best Practices
• Jira and Jira Align Integration: Issue Best Practices
• Jira and Jira Align Integration: Issue Field Best Practices for Create and Edit Screens 
• Jira and Jira Align Integration: Workflow Best Practices
• Jira and Jira Align Integration: Story Resolution Transition Best Practices 

[MichaelL]

If I opt to no longer sync fixVersions, I would have to manually create Release Vehicles in Jira Align and assign these to Jira Align work items (Features, and possibly Stories and Defects).   That in and of itself is not a big deal.

But then, if I revise a fixVersion on a Jira issue, the Release Vehicle on the corresponding work item in Jira Align will not automatically update.  Likewise, if I update a Release Vehicle value on a Feature in Align, the corresponding Feature (Epic) in Jira will not update its fixVersion.  I would be forced to somehow manually reconcile the Release Vehicle values in Jira Align work items with the fixVersion values in the corresponding Jira issues.  And I would have to do this periodically.

How could I perform such a reconciliation and know at a glance which value -- the Release Vehicle in the Jira Align work item, or the fixVersion in the Jira issue -- should take precedence when they do not agree?  How could I generate a report without going through tedious exports?  How can I avoid spending lots of time pouring over Excel and manually editing the corresponding work items or issues to get them to agree?

What I've been doing is allowing fixVersion and Release Vehicle to sync.  I establish distinct Release values in each Jira project.  So instead of four team-level Jira projects (e.g. with keys TLA, TLB, TLC and TLD) each having one Release named 1.0.0, they would each have one Release named A 1.0.0, B 1.0.0, C 1.0.0 and D 1.0.0, respectively.  Likewise, the corresponding Features in the program-level project in Jira would have 4 releases such as PL A 1.0.0, PL B 1.0.0, PL C 1.0.0 and PL D 1.0.0.  This gives me a total of 8 distinct Releases (8 fixVersions) in Jira.  And once synced, I'd get 8 corresponding Release Vehicles in Jira Align -- all for a single 1.0.0 release (across a suite of products).  That's an awful lot of fixVersions and Release Vehicles to track...

An Aside:  I could refine my scheme a bit and create only 5 releases total by adding only a single Release value of 1.0.0 to the PL project.  But in my company, version 1.0.0 of product A may ship before 1.0.0 for product B, and so on - so separate Releases for the Epics/Features allow for distinct ship dates for the four products.

...But at least these 8 releases would have distinct names (so no duplicate Release Vehicles in Align).  And I do not have to worry about reconciling edits to fixVersion or Release Vehicle field values on individual issues and work items between Jira and Jira Align.  I suppose I can group the 8 related Release Vehicles on the Jira Align side to make this a little less incoherent.

But this is sheer nastiness.  There has got to be a better way to manage releases:  an enhancement to Jira Align so there would be an option to allow many releases in Jira to map to a single Release Vehicle in Jira Align.  Ideally, this mapping could be done automatically based on a user-specified Release format (e.g. a RegEx so the example 8 release values in Jira I mentioned earlier could be automatically mapped to a single new Release Vehicle called 1.0.0).  And any change to a work item's Release Vehicle value would sync back to the corresponding Jira issue, using the appropriate release format, e.g. setting a Story work item to Release vehicle 1.4.0 would sync to the corresponding Jira issue in the TLB project as fixVersion B 1.4.0, via the automatic mapping. 

Or perhaps something even simpler and easier.

By keeping fixVersion and Release Vehicle synced, I believe Jira Align can note the ship date for the Release value associated with each fixVersion it encounters, and use that to automatically assign Program Increment to a work item (I may be wrong about how this works, but I think there is something to it).  if I disable the sync, I lose that auto assignment and now have to manually maintain the Program Increment field in Jira Align work items as well.

[Jeff Timmins]

This really scares me, I was thinking Jira Align would make Release tracking easier ....

[Kendall Alton]

@Jeff Timmins , this issue has been discussed for years. In October 2021, I was informed by an Align support person that this issue was resolved, but have not seen any updates to support the claim.  Sidebar: this doesn't help the Align integration issue, but alternative ways to have predicted release dates might be to leverage other tools.  If a reporting tool, e.g. Tableau, is used, then a transformation/normalization could be performed to generate version-based burndown charts.  eazyBI also has a version burndown report, but it doesn't have a normalization method, so constrained to each project's fixversion.  When using the ALM Structure plugin, the problem is not as prevalent, since it can group on metadata values. However, a predicted date based on version isn't readily available.  Unfortunately a lot of partial solutions and no clean answer.