Jira Fix Versions Management Guideline

Create Versions in Jira:

1. Navigate to your Jira project and
   1. go to Project Administration OR
   2. go to Manage Versions on Releases page

2. In the Project Administration menu click on Versions

3. Fill in Version name, Version Description and Start date, and click Add

4. Use Drag&Drop to rearrange order of Versions in the list

I. Make sure three required Versions are created for each Jira project corresponding to the modules and other FOLIO software components (plugins, libraries, etc.) owned by a team and meaningful Version Descriptions are added:

1. Next Patch Version - version (x.y.Z) with Z incremented
2. Next Minor Version - version (x.Y.z) with Y incremented
3. Next Major Version - version (X.y.z) with X incremented

Note: The above mentioned Versions must be increments based on the Version of the latest Quarterly Release delivered (created in GitHub). 

II. For a module to support updates into the last two quarterly releases an additional set of versions might be required:

1. QX Next Patch Version - version (x.y.Z) with Z incremented
2. QX Next Minor Version - version (x.Y.z) with Y incremented

Note: The above mentioned Versions must be increments based on the Version of second-to-latest Quarterly Release delivered (created in GitHub). 

• Three required Versions should be created for every Jira project, so that an appropriate Version can be selected by any developer based on the nature of their task. Most developers do not have permissions to add Versions to Jira projects, thus three required Versions should be created in advance to be available for developers when needed. 
• For modules where support of the last two quarterly releases is often required it makes sense to add an additional set of versions for second-to-latest Quarterly Release to be available at any time. 
• There can be cases with more Versions available because of requirements to create additional Hotfix releases for some previously delivered quarterly releases - such Versions can be added when needed. 

Update Fix Version field in a Story/Task/Bug selecting an appropriate Version after code changes have been merged:

1. On View Issue screen update Fix Version field by selecting an appropriate Version from unreleased versions available in the dropdown;
2. OR from Backlog view select a story/task/bag and use Drag&Drop to associate it with a proper Version in Versions left side bar;
3. OR from Edit Issue screen update Fix Version field by selecting an appropriate Version from unreleased versions available in the dropdown

There should be at least three unreleased Versions available: 

• Next Patch Version - version (x.y.Z) with Z incremented
• Next Minor Version - version (x.Y.z) with Y incremented
• Next Major Version - version (X.y.z) with X incremented

If changes are implemented for second-to-latest Quarterly Release, there should be corresponding unreleased Versions available (or they must be created ad-hoc):

• QX Next Patch Version - version (x.y.Z) with Z incremented
• QX Next Minor Version - version (x.Y.z) with Y incremented

Note: If a fix is to be backported to previous quarterly releases and delivered as Bugfix/Hotfix release, it is necessary to specify several Fix Versions to identify in which Version of every quarterly release the fix was introduced.   

Example of several Fix versions specified for an issue:

Three Fix Versions should be specified (1.5.2, 1.6.4, 2.1.1) to indicate that the fix:

• is included into Q3 v2.1.1 and onwards
• is backported to Q2 in v1.6.4
• is backported to Q1 in v1.5.2 
• is not available in any Q1 versions before v1.5.2, any Q2 versions before 1.6.4, and any Q3 versions before 2.1.1

• Developer is accountable for updating Fix Version field and selecting an appropriate Version based on the nature of implemented changes after code changes have been merged.
• Scrum Master is responsible for reviewing closed issues on regular basis (after every sprint closure) to make sure Fix Versions are not missed (go to Jira Sprint Report → View in Issue Navigator → Review Fix version column in List View mode). If missing Fix Versions are observed (and there were code changes associated with those items), Scrum Master should work with their team to fill in the gaps. 
• Fix Version should not be specified for any stories/tasks having no code changes merged. For example, spikes, investigations, POCs, tasks closed with resolution Won't Do/Duplicate/Cannot Reproduce and other tasks having no code changes impacting production release artifacts. 

3 weeks prior established module release deadline 

Update Fix Version field in an incomplete Story/Task/Bug being not yet merged, if it is confirmed to be a release must-have item.  

When Fix Version added to incomplete must-have items:

1. Incomplete release must-have items will be added to the scope of corresponding Versions on Releases page of a Project
2. Details on the incomplete release must-have items and their current statuses can be viewed on Version details page and used for understanding of module readiness for release

Note: If some incomplete item is not assigned to an appropriate Version in Jira in time, there is a great chance it won't get into Release as the team owning a module can start Release procedure earlier than the item is completed.  

• Product Owner is accountable for reviewing Release progress and identifying incomplete release must-have items 3 weeks prior established module release deadline.
• Developer is accountable for updating Fix Version field and selecting an appropriate Version based on the nature of code changes planned to be implemented for the items confirmed to be release must-haves.
• Scrum Master is responsible to make sure release progress review is done by a team and Fix versions are added for incomplete release must-have items.
• Release Coordinator is responsible to add this action to Release timeline.

While creating a release during Release sprint

I. Confirm the Version to be released and Delete unnecessary Versions:

1. if there are items in Patch Version only, Patch Version to be released: 

→ Patch Version is planned for release

→ No need to delete any Versions

2. if there are items in Minor (and Patch) Version AND no items in Major Version:

→ Minor Version is planned for release

→ Patch Version must be deleted; while deleting - all issues assigned to Patch Version must be moved to Minor Version planned for release to be included into corresponding Release notes

3. if there are items in Major Release (and Minor/Patch) version: 

→ Major Version is planned for release

→ Patch and Minor Release versions must be deleted, while deleting - all issues assigned to Patch/Minor release versions must be moved to Major Version planned for release to be included into corresponding Release notes

II. Proceed with Release Procedure for a module:

a. if all items assigned to a Version are completed

→ Proceed with Release Procedures

b. if 4 days before release deadline there are still some incomplete items assigned to a Version

→ Proceed with Release Procedures

→ Incomplete items won't be included into release and Fix Version field should be cleared for them. 

Note: Relevant POs should be informed that release procedures are going to be started and some incomplete items should be planned for next quarterly/Bugfix/Hotfix releases. In case it is not possible to defer incomplete items to next quarterly/Bugfix/Hotfix release and the decision is to postpone release creation to get critical items completed and included, the risk of delay of a module release (and any dependent modules' releases) should be explicitly raised.

Note: Before releasing - double-check if there are any items completed with Fix Version missed in Jira. If there are any - Fix versions should be added to get the items included into Release Notes in Jira.  (see Template Filter → update "project" and "resolved" date (=Start date of a Version to be released) to see items Closed without Fix Version since the work on that Version had been started)

For more details on Release Procedures see:

• Community Release Guides

• Before starting release procedure for a module, all completed issues planned for next quarterly release for a certain module must be reviewed to confirm which Version is going to be released (patch/minor/major).
• Deleting unnecessary Patch/Minor Versions is necessary if they are not going to be released separately, so that all issues completed and assigned to Patch/Minor Versions are moved to a Version to be released and are included into its Release Notes in Jira.
• Having a cut-off day (4 days prior release deadline) is necessary to avoid postponing release procedures until the very last day and thus having delays in releases of interdependent modules. 
• Scrum Master is accountable for deletion of unnecessary Versions in Jira and moving issues to a Version planned for release as well as clearing Fix Version field for the incomplete items, not included into release.
• Dev Lead can be responsible for deletion of unnecessary Versions in Jira and moving issues to a Version planned for release as well as for clearing Fix Version field for the incomplete items, not included into release, if agreed within a team, but Scrum Master remains accountable for making sure the Version to be released is confirmed, unnecessary Versions are deleted and Fix Version field is cleared for the incomplete items not included onto release.
• Release Coordinator is responsible for regular monitoring release readiness status across FOLIO and sharing the updates via Slack channel and while Release Weekly Status Review meetings. (the report can be fetched based on incomplete items assigned to Version planned for release + blockers/dependencies linked to release stories)
• Release Coordinator is responsible for double-checking the release readiness status on the agreed cut-off date and informing about the modules still having incomplete items, so that all parties involved can clearly understand that release procedures are going to be started and some incomplete items won't be included into release. 

After Release in GitHub is created

I. Release corresponding Version in Jira:

1. Release Version in Jira

2. Add Release date while releasing Version in Jira

3. Update released version description to easily identify relevance to a certain quarterly release

→ [QX yyyy (Hotfix/Bugfix) Release: GitHub Release URL] 

II. Update/add required Versions for next releases:

a. if Patch Version was released

→ Add next Patch Version 

→ No updates for Start date for Minor and Major Versions

b. if Minor Version was released:

→ Add next Patch and Minor Versions

→ Update Start date for Major Version

c. if Major Version was released:

→ Add next Patch, Minor and Major Versions

• Scrum Master is accountable for releasing and updating Versions in Jira as soon as corresponding modules are released.
• Dev Lead can be responsible for releasing and updating Versions in Jira, if agreed within a team, but Scrum Master remains accountable for making sure the Version are released and updated.
• Release Coordinator is responsible for monitoring the number of unreleased Versions per Jira project across FOLIO and sharing the updates via Slack channel.