DRAFT: 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

• Scrum Master is accountable for creation of required Versions in Jira projects corresponding to the modules and other FOLIO software components (plugins, libraries, etc.) owned by their team (see Team vs module responsibility matrix).
• Dev Lead can be responsible for creation of required Versions in a team's Jira projects if agreed within a team, but Scrum Master remains accountable for making sure required Versions are created in Jira projects.
• TBC: Permissions to create and manage Versions in Jira are granted under "project-admins" group and should be requested from ____. 

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 another set of three versions is 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
3. QX Next Major Version - version (X.y.z) with X 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 three versions for second-to-latest Quarterly Release to be available at any time.
• There can be cases with more unreleased Versions available because of requirements to create additional Hotfix releases for some previously delivered quarterly releases. 

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 delivered, there should be corresponding unreleased Versions available:

• QX Next Patch Version - version (x.y.Z) with Z incremented
• QX Next Minor Version - version (x.Y.z) with Y incremented
• QX Next Major Version - version (X.y.z) with X 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 releases 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.

2 weeks prior established module release deadline

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

1. if there are items in Bugfix release version only or if a Bugfix/Hotfix Release is required: 

→ Bugfix release version is planned for release

→ No need to delete any Versions

2. if there are items in Minor Release (and Bugfix) version AND no items in Major Release version:

→ Minor Version is planned for release

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

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

→ Major Version is planned for release

→ Bugfix and Minor Release versions must be deleted, while deleting - all issues assigned to Bugfix/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 as soon as all the items assigned to a Version planned for Release are completed:

a. if all items assigned to a Version are Closed or Awaiting Bugfix release

→ Proceed with Release Procedures

b. if 4 days before release deadline there are still some incomplete items

→ Proceed with Release Procedures

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

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 date of previous Release to see items resolved without Fix Version since previous Release)

For more details on Release Procedures see:

• Community Release Guides

• 2 weeks prior established release deadline all the complete and incomplete issues planned for next release must be already assigned to corresponding Versions in Jira by all development teams involved, thus it must be possible to confirm at this point which Version is going to be released.
• Deleting unnecessary Bugfix/Minor Versions is required if they are not going to be released, so that all issues completed and assigned to Bugfix/Minor Versions are moved to a Version planned for release 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 
• Dev Lead can be responsible for deletion of unnecessary Versions in Jira and moving issues to a Version planned for release, if agreed within a team, but Scrum Master remains accountable for making sure the Version to be released is confirmed and unnecessary Versions are deleted.
• Release Coordinator is responsible for 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)

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 Bugfix Version was released

→ Add next Bugfix Release version 

→ Update Start date for Minor and Major Release versions

b. if Minor Version was released:

→ Add next Bugfix and Minor Release versions

→ Update Start date for Major Release version

c. if Major Version was released:

→ Add next Bugfix, Minor and Major Release 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.