Considering SDLC in Jira, but not sure how to manage the versioning of requirements?

[#1]

When moving SDLC into Jira, requirements management is the first issue to look at.

The most effective way to manage requirements in Atlassian is to create a custom work item type specifically designed for them. This approach enables you to customize the terminology and hierarchy in Jira to align with your unique needs. By designating requirements as a separate work item type, you can effectively address a key distinction between requirements and development stories: the longevity of requirements. Once a story is implemented, it can be closed. However, Requirements established for the initial version of a product often remain relevant for many years.

While this holds for most requirements, it's important to note that they can evolve alongside your product or system. Consider a requirement that allows users to authenticate using a username and password. Over time, you may enhance this by incorporating multi-factor authentication (MFA) or other methods. Essentially, this represents the exact core requirement, but in an evolved form.

The need to update requirements to reflect the product's evolution raises an important question: What is the best way to manage the evolution of requirements in Jira? The answer is not obvious since Jira lacks a proper versioning system for its work items.

Over the years, I've encountered several practical approaches to versioning requirements in Jira. In this article, I'll explore the key solutions that have proven successful for teams in real-life scenarios.

Interested to learn more about SDLC in Atlassian? Read on about it in my series: "Ready for an SDLC shakeup? The good, the bad, and the ugly of managing requirements and tests in Atlassian"

If you have witnessed or implemented other methods, please share your experiences in the comments.

Keep it simple: allow requirements to change

The first option is to allow requirements to evolve. When a requirement needs to be updated, you modify it in Jira.

Updating the Jira work item will not impact your compliance posture if you maintain full historical release documents for previous versions. Moving forward, you can only use and link to the updated version of the requirement.

To implement this option, you'll configure workflows that ensure related work items also reflect the changes made. A practical approach requires users to revert the requirement to an earlier status within the workflow.

For example, once a requirement is implemented and designated as 'IN PRODUCT' (workflow status), it cannot be edited. When an update is necessary, the requirement transitions to 'DRAFT.'

The requirement can be modified while in the 'DRAFT' status. However, it transitions back to 'IN PRODUCT' only when linked work items, such as tests and other requirements, have been updated to reflect the changes made.

Workflow conditions and automation can help synchronize and realign updated requirements with other work items.

This approach is well-suited for simpler products, where only one version is actively developed, and a single version is in production. However, it does not work when a team simultaneously needs to support release updates for multiple product versions.

Simple manual versioning: allow requirements to evolve and document changes in the Description field.

This approach builds on my first method, allowing the same work item to evolve over time. Updates are explicitly documented in the Description field, providing good visibility of changes.

This method is manual and requires discipline from the required authors. Additionally, links to other work items can be ambiguous. For instance, if a requirement is associated with multiple tests, the links might only be applicable to certain versions. The Fixed Versions field of the test issue can resolve this ambiguity, but this is not as obvious as the Fixed Version field of the requirement itself.

Update by replacing: each requirement has a single effective version

A third approach to requirements versioning is to disallow updates to existing requirements. When a requirement needs to change, a new requirement is created, and the old one transitions to a canceled status. The Fix Versions field (or a custom version field) can indicate the specific product releases to which each requirement applies. Subsequent product releases will not be associated with canceled requirements.

When replacing a requirement with a new work item, the linked work items also need to be managed. For instance, while many tests designed for the previous requirement may still be applicable to the new one, some tests will become outdated and need to be replaced.

This approach is the most commonly used and is well-suited for complex products and large teams. It enables teams to manage development efforts across multiple product versions effectively.

Elaborated multi-versioning: using parent/child relations in Jira

The final approach leverages Jira's capability for parent/child relationships. In this model, the primary or master requirement acts as the parent, while all its versions serve as children.

This implementation relies heavily on advanced configuration and automation to ensure the constraints and synchronization of the various requirement versions. For example, each product release is linked to a specific version of the requirement—provided that the requirement has not been retired.

While this solution offers a comprehensive structure, it is also the most complex to set up and understand. A product manager or business analyst may find it difficult to understand the approach and work with it effectively.

This approach works well for complex products and larger, mature teams. Use it only when it is important to maintain a clear record in Jira of how the different versions of requirements have evolved over time.

Integrate versioning into the workflow

Regardless of your chosen approach, you'll need to consider the workflow associated with requirements. Generally, the workflow should facilitate drafting, reviewing, and approving requirements before implementing them and releasing them as part of the product.

After release, the workflow will vary depending on how you handle requirement updates. Additionally, you can enhance the workflow with automation rules to ensure alignment with other work items in your product's SDLC, such as tests, stories, and defects.

Choosing the right approach to versioning requirements

I recommend starting with the most straightforward approach you can effectively manage—this should always be your default position. Especially so because SDLCs is always a non trivial process anyways. You can easily transition to a more advanced method if you discover compelling reasons to adopt a more complex solution. With Jira, you have a robust platform for managing requirements, allowing you to increase complexity as needed.

Read more about SDLC in Atlassian.