In Jira we have the concept of Sprints and Versions. We've already covered Using Jira JQL to Search for Issues in a Sprint. In this post we look at JQL statements and functions you can use to search based on Versions.
A Version in Jira is a milestone in your project. Think of it as a 'name' that points to a snapshot of something you want to release. Usually we'll have two version fields
1. Affects Version – the version of the app/product where we found the issue
2. Fix Version – the version of the app/product where we included the fix for the issue
You may need to configure your issue layout to show both of these fields. If your configuration is setup correctly then you should see them in the details section of the issue page:
Jira Version Fields
All of this depends on where you set them to be displayed. Anyway, there's one other point about Versions that we must consider.
A Version can be considered 'Released' or 'Unreleased' or 'Archived'. In general you've either pushed the version out of the door (Released), you're still working on it (Unreleased) or you no longer care about it and want to hide it (Archived). You'll define this state in the 'Releases' section of Jira.
Jira Version Release Status
Actually, there is another thing. Don't forget that an issue can have 1 or more Version values for both Fix and Affects version. You can see this in the image below where the Affects version has two versions linked.
Jira Version Fields
Simplest why to get started with JQL on versions is to click that version name (it's a hyper link). This takes you to the search screen and should show you the JQL used to search for that version (you might need to click the 'Switch to JQL' link).
Jira JQL searching for versions
So the JQL fields we have to play with are identified in JQL with “affectedVersion" and “fixVersion"
Jira JQL version fields
An example with affectedVersion looks like this
project = "ATC" AND affectedVersion = "Version 2"
And with “fixVersion"
project = "ATC" AND fixVersion = "Version 2"
And of course you can search with both fix and affected using the “AND" clause …
project = "ATC" AND fixVersion = "Version 1" and affectedVersion = "Version 1"
If you want to find issues in multiple versions then the IN clause is useful
project = "ATC" AND fixVersion in ("Version 1", "Version 2")
Which is the equivalent of using the OR clause…
project = "ATC" AND fixVersion = "Version 1" or fixVersion = "Version 2"
But watch out!! What this has given us is “Version 2" for ALL projects. You'll want to narrow this down by putting brackets round the 'fixVersion' conditions.
project = "ATC" AND (fixVersion = "Version 1" or fixVersion = "Version 2")
This way project is ATC 'and' fix version is 'either ' version 1 or version 2
Right! That's the easy stuff what we really want to look at is the useful JQL functions Jira gives us
releasedVersions()
unreleasedVersions()
latestReleasedVersion()
earliestUnreleasedVersion()
In relation to the version fields this gives us
Jira JQL Version Functions
Perhaps we want to find all issues fixed in versions we’ve released. That’s the fixed issues in versions that are marked as ‘released‘ here…
Jira Versions Released and Unreleased
Then we can use the `releasedVersions()` JQL function to pick up on only issued that have been released.
project = "ATC" AND fixVersion in releasedVersions()
Which can be shortened to …
fixVersion in releasedVersions(ATC)
And guess what? We have the opposite of this which is `unreleasedVersions()`…——————
fixVersion in unreleasedVersions(ATC)
Which is all issues that are linked to Versions that have not yet been marked as released.
Or if you're interested in 'affected version' issues
affectedVersion in unreleasedVersions(ATC)
Which Finds issues in versions where the version hasn't been released yet.
If you want to narrow this down to the 'last' release then use JQL like this…
fixVersion = latestReleasedVersion(ATC)
It's really important to note here, that the “latest" is determined by the ordering assigned to the versions, not by actual Version Due Dates. In the example below 'Version 2' is the latest release because it is ABOVE Version 1 in the list (not because it has a later release date).
Jira Versions Release Date Order
The equivalent for unreleased issues is the `earliestUnreleasedVersion()` function.
fixVersion = earliestUnreleasedVersion(ATC)
Think of this as “I’m interested in the issues in my NEXT release“.
Again Version order is determined by the order versions are placed in on the **Releases** page in the project. The version at the bottom of the list is considered the “earliest." To change the order of versions, drag and drop them to a new place in the list.
Just to summarise then…
Jira JQL Version Functions
Something else to be aware of are the different uses of the 'in' and '=' clauses.
fixVersion = latestReleasedVersion(ATC) => singular
fixVersion in releasedVersions(ATC) => plural
If a function is 'plural' (i.e. it ends in an 's') then it will return a list of values. If you're looking at a list of values then you need to use the 'in' clause.
JQL functions that return lists
If a function returns a single value (i.e. it's singular and doesn't end in an 's') then you use the '=' clause.
Jira JQL Lists
And that's about it for JQL and versions. This should give you all you need to power search for issues based on Versions using JQL.
