---
title: "Using Versions with Xray"
canonical: "https://docs.getxray.app/space/XRAY/351338528/Using%20Versions%20with%20Xray"
format: markdown
---
> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> > Macro (toc)

# Overview

In any software development lifecycle, proper versioning underpins traceability and repeatability. With Xray for Jira, the `FixVersion` field plays a central role in version-based planning, Test coverage, and release readiness.

This guide explains how and when to use Versions effectively (or when not to use it at all) and how your Testing processes can adapt across Agile, Waterfall, or hybrid cross-project models.

> 📝 [Versions](https://support.atlassian.com/jira-software-cloud/docs/what-is-a-version/) is a Jira concept for grouping work together targeted for a given release; it’s implemented using a dedicated custom field (*FixVersion*) used by Xray for release alignment and traceability.

# Choosing a Strategy: Using Versions or Not?

> ℹ️ Most teams benefit from using Versions, especially when supporting multiple releases or components. However, continuous delivery models may operate without them for speed and flexibility.

# Understanding Project-Level and Aggregated Versions

## Project Versioning

Each Jira project has its own version space for managing “versions”. These represent a single product or component-level release identifiers:

| **Project** | **Version** | **Test Scope** |
| --- | --- | --- |
| Calendar.app | v11 | Component/Feature |
| Mail.app | v13 | Component/Feature |

Versions are assigned to:

- Requirements / Stories → to plan features tied to a release.
- Test Executions / Test Plans → to tie testing results to that release.

## Multi-Project Aggregation

When aggregating multiple products or components into a unified platform, use a parent or integration project with its own versioning:

| **Aggregated Project** | **Version** | **Test Scope** | **Component/Library Projects**<br>**(i.e., other projects that are key to the aggregated project)** |
| --- | --- | --- | --- |
| DesktopOS XPTO | v23H2 | Integration<br>E2E<br>Acceptance | Calendar.app v11 |
| Mail.app v13 |

In this setup:

- Component/Library teams test and deliver independently using their versions.
- Integration team uses a separate version (`DesktopOS XPTO - v23H2`) for integration and acceptance Testing.
- Test Executions or Test Plans in the integration project reference Test cases from component projects.

> ℹ️ Ownership remains within original projects, but execution and reporting for release-level readiness occur in the aggregate project.

# When Not to Use Versions

In CI-first and continuous delivery environments:

- Teams may avoid assigning *FixVersions* altogether.
- Test cases and executions are tied only to Issue links and Test environments.
- Reports reflect only the current state (i.e.: “all Tests passing for current main branch”).

> ✅ This works well if:
> ✅ 
> ✅ - You’re always working on the “latest”.
> ✅ - You don’t support long-lived release trains or historical Test audits.
> ✅ - Testing is triggered dynamically through pipelines without needing Test packaging across.

> ⚠️ Reminder: without versions, you lose the ability to later trace which Tests were executed for which release, making it harder to support audits, hotfixes, or regression tracking. You may nevertheless assign the build number, for example, on the Revision field of the Test Execution to clearly identify the build where certain results were obtained.

# Methodology Adaptation: Agile and Waterfall

Xray and Jira adapt well to both Agile and Waterfall methodologies, provided versioning is used sensibly.

### Agile

**Scrum**

- Use *FixVersions* to mark upcoming releases “Release 2.5”.
- Assign versions to:  
	•	Stories / Requirements.  
	•	Test Executions.  
	•	Test Plans.
- Assign work items to sprints (i.e.: “Sprint 27”):
  - Stories / Requirements.
  - Test Executions (optional).
  - Test Plan(s).

> ℹ️ Enables release-based test coverage, clean Test traceability.
> ℹ️ 
> ℹ️ Also provides the ability to analyze coverage based on the results obtained within the sprint, by analyzing coverage and traceability using the Test Plan as the analysis scope instead of the version/release global results.

**Kanban**

- Teams may or may not use versions.
- If versions are used: helpful for planning fixed-scope deployments or epics.
- Without versions: follow continuous testing tied to recent Issues only.

### Waterfall

> ❌ Common misuse: Jira does not have native Milestones. A common mistake is trying to represent Milestones as *FixVersions*. Don’t do it.

Recommendation:

- Using Releases to define the Versions, by assigning work items to them through the *FixVersion* field.
- Using Test Plans to represent internal milestones within a release (e.g., Alpha, Beta, UAT, Regression cutoffs) and set to define the Milestone implicitly in its summary, or using a dedicated Milestone custom field.
- Linking associated Tests and Test Executions to these Test Plans to track progress Milestone-by-Milestone.

> ✅ Tip: use a dedicated custom field for Milestones. This field can be used to identify the specific Milestone or be easily identifiable in Stories or other Issue types that are defined as requirements for each Milestone:
> ✅ 
> ✅ **Story**
> ✅ 
> ✅ - FixVersion = 3
> ✅ - CF Milestone = 2
> ✅ 
> ✅ **Test Plan**
> ✅ 
> ✅ - FixVersion = 3
> ✅ - CF Milestone = 2

This keeps the versioning space clean and focused, while using existing Issue hierarchies to manage Waterfall phases.

# Final Considerations

Deciding when and how to use Versions in Xray comes down to how your team delivers software:

- For structured, multi-train, or enterprise delivery models, using versions is crucial.
- For fast-paced or monolithic pipelines, a less formal versioning may suffice.
- Cross-project coordination should rely on version aggregation with scoped integration Testing, not a shared global FixVersion.
- For Waterfall teams especially, use Test Plans as Milestones, not Versions.

Adopting versioning strategies in alignment with your delivery and quality process ensures:

- Reliable regression coverage.
- Traceable quality signals.
- Clean audit and reporting history.


<details>
<summary>Support/Troubleshooting</summary>

If you have questions or technical issues, please [contact the Support team via the Customer Portal (Jira service management)](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28) or [send us a message using the in-app chat](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301501383).
</details>