How to simplify PI tracking in Jira

Originally published August 4, 2020

Your organization faces a number of choices for how best to navigate its Scaled Agile Framework (SAFe) transformation. We’ve already written about how to decide which hierarchy to use and how to efficiently manage PI planning. Another important question you'll have to answer: how to represent and track PIs.

The common approaches are:

• fixVersion

• creating a "PI" Jira issue

• custom fields

• components

• labels

We’ll briefly go over the rationale behind each idea, and help you consider which solution best suits your company's situation.

FixVersion

A very common approach to tracking PIs is to attach them to the fixVersion field in Jira. This is the most semantically in line with each PI, resulting in a working release and aligning with your release cadence. We recommend this option wherever possible. However, you will need to decide between working on a single central fixVersion, or creating a fixVersion for every team (all with the same name).

The flexibility allowed in naming your fixVersion may create confusion if you’re not careful. For example, while these fields are not case-sensitive (“PI Elephant” will also be found by a query searching for “PI elephant”), there are often cases where spelling issues or poor communication can lead to errors (for example “PI Elephant” is not the same as “PI - Elephant”). There is no built-in validator for fixVersion, so you’ll need to ensure consistency in some way if you select this. Note that other options also involve potential pitfalls with regard to naming, so always think through the downstream naming impacts of your decisions before you move forward.

One case where we do not recommend fixVersion fields: when they are currently being used as part of your release management and if those releases are on a different cadence than your PIs. Using fixVersion for PI tracking might be impossible in that case — or, at minimum, they can introduce complexity, hurt reporting, and disrupt other downstream processes.

Creating a "PI" Jira Issue

If fixVersions won't work for your release cadence, and if you are starting from a clean-slate Jira, your next-best option may be to create a Jira issue called "PI" and use issue links to track it. Many consultants use this as their SAFe solution, as it's almost identical to using fixVersions if you also connect the PI to the parent epic/initiative.

However, it requires a fair bit of organizational discipline. You would need validators or other rules in place to prevent mis-naming problems that would lead to mass confusion. If your Jira instance and users are disciplined, it's a solid option — but poorly implemented, it can lead to a lot of pain.

Custom fields

Custom fields are probably the easiest to implement if using fixVersions is not available to you. You can make a select, numeric, or general text field:

• The select field is the easiest for users, but will require you to periodically add the newest ones, and after several PIs you will likely be adding complexity by having an ever-growing list of options to choose from. You could change this down the line from one to another, but it will require some careful scripting.

• A numeric field may be easier to edit, since you can keep incrementing them each PI. It also nicely adds an indication of how long you have been on your Scaled Agile journey. However, this does limit your naming ability, so you’ll need to make sure this is something that is acceptable to your organization. Generally you will want to avoid having things with multiple names. For example, it would likely cause confusion if Jira has all PIs by number, but documentation refers to them by animal names.

• Finally, having a generic text field is the most flexible, but also a possible source of naming errors — similar to the kinds of mistakes that can arise from using fixVersion fields, except in this case you could wind up with different names for every issue!

The downside here is that custom fields can often lead to bloat. Adding several values within a single custom field — for example, if everyone is entering a unique response in the generic text field — can quickly lead to confusion. We recommend custom fields only if using fixVersion is not an option.

Components

Another common approach is to add a component to track which PI an issue belongs to. Components are a subsection of projects — bigger than issues, but smaller than the project itself. They come with Affect Version and fixVersion links, as well as their own resolution rules.

Some elements make this useful: You can assign a component to a person, such as the release train engineer (RTE). That way, the RTE has an easy way to aggregate all the issues under their control. They can create their own board or structure to keep an eye on issues and deadlines, making their life considerably easier.

Components are also a decent option if fixVersions would be too complicated for your organization's setup. Here's why: Release versions are defined per project, and if you want to link all the stories to a PI, you need to create fixVersions in each team's project as well as the program level above it. But that might lead you to override a team's process for release management. For example, if the ART has a software team in it, but also a marketing or administrative team, the software team could be managing their own releases with fixVersions and they now lose a key feature just so the larger team can use the same field.

Components, then, offer a compromise.

The biggest drawback to using components is that every issue must be linked to its component, and it’s easy for users to forget to add a link. Jira can alert you to linking mistakes with fixVersion, but components don’t have similar safeguards.

Labels

Many organizations consider using labels to track PIs, but this isn’t something we recommend. Labels are too flexible and meant to denote bits of information where an issue is out of the ordinary (was it escalated, contracted out, etc.) whereas PI information is something that is a single value for each issue. Organizations also tend to have lots of loose rules for how labels are used, and adding PI to an already polluted namespace is a recipe for confusion and disaster.

Lastly, labels are hard to aggregate and filter by — this is most relevant for Structure users, but it applies more generally as well. Using labels to keep track of this information means you constantly need to take extra steps to get a clean data set to work with.

Final analysis: How to choose

As with everything, much depends on your organization's unique situation and what works best for your team. But here are a few key thoughts to leave you with:

• FixVersion fields are the best choice, unless your release management process doesn't easily allow for them.

• Creating a "PI" Jira ticket can work well, as long as labeling rules are incredibly stringent and uniformly applied.

• Custom fields are the easiest non-fixVersion options to implement, but you have to make sure your team is incredibly disciplined in how they add values to prevent constant confusion.

• Components offer a compromise if fixVersion fields aren't neatly aligned with your releases, and they have other benefits — such as the ability to assign them to an individual. But again, human error is a factor here. Every issue must be linked to its component, and it's easy to forget to do this. Only consider this option if you have a thought-out way to incorporate this functionality into your reporting and management.

• Labels seem like a good idea, for about two minutes. Don't use labels.

Another key thing to remember is that these options rely on clear naming conventions that users follow carefully. It's easy to accidentally pick a naming convention that might lead to confusion, so be aware of downstream impacts.