Jira Versioning Process using Nested Versions

Icon

This page is intended to spell out the naming convention for Garmin Connect versions and how affects versions and fix versions are managed in Jira with the development and deployment of Garmin Connect.

Version Naming Convention


Versions in Jira are merely strings, so you can assign whatever characters and numbers you want to the name of a version. You can also order them and create hierarchical associations however you want. We have decided to use a numbering system using the following convention.

<version-major>.<version-minor>.<build-major>.<build-minor>

version-major and version-minor

The version-major and version-minor are nothing more than sequential numbers we use for communicating internally. The first non-beta GC release was 1.0, and from there on out we increment the version-minor with each release cycle. Once the version-minor gets to 9, we increment the version-major and drop the minor back down to 0. So the next release after 1.9 is 2.0. The jump to an incremented version-major is insignificant, we just decided to keep our version-minor in the 0-9 range and increment the version-major once we've hit a version-minor of 9. We never jump from 2.7 to 3.0 because there was a big enough improvement - we just blindly increment the version-minor for each release cycle until the version-minor hits 9 and then we roll over to 0 with an incremented version-major.

build-major and build-minor

Every deploy to production is a new build major. So the first release of 2.7 is actually 2.7.0. The build-major is reserved for each patch or BAU (if new artifacts are deployed) to production between releases of a new version-minor. This occurs as often as every week, so we could deploy 2.7.0 and then a 2.7.1 the following week and a 2.7.2 the following week after that. On rare occasion we may need to immediately patch a patch and in that case we typically just get lazy and call it the same build-major even if it does include new artifacts.

The build-minor indicates the internal build number. During development, we assign a new build-minor to each of our weekly test deploys, our regression testing candidate, and our staging release candidate. So the first internal build of 2.7 is actually 2.7.0.1, the second is 2.7.0.2, the third is 2.7.0.3 and so on. Once we get to staging, this trend continues with each build to staging. So we may deliver 2.7.0.5 to staging, perform a few rounds of fixes and deploys to staging, and end up with 2.7.0.10 as our version to release to production. The moment we release to production we drop the build minor and refer to 2.7.0.10 as 2.7.0. And then when we begin on the first 2.7 patch, we refer to the next production deployment as 2.7.1, and the first internal build to staging for 2.7.1 as 2.7.1.0. We may have another few rounds of builds for 2.7.1 and end up with 2.7.1.2 that we want to deploy, so after we do we once again drop the build minor and just call it 2.7.1.

Rules of Thumb

  • Every deploy to Test with new artifacts merits a new build-minor
  • Every deploy to Staging with new artifacts merits a new build-minor
  • Every deploy to Production with new artifacts merits a new build-major
  • Every BAU deployment to production with nothing but config admin changes should re-use the fix version of what is currently on production

Version History Example


Version

Release Date

Description

Notes

Managed By

2.7.0

02/Dec/09

Edge 500 support, GPX support, Google Earth plugin, new Details page beta

This is the parent version for all 2.7.0.X versions. It encompasses everything that is in the initial 2.7.0 production deployment. But 2.7 patches are managed in subsequent 2.7.X versions.

Development Team

2.7.0.0

10/Sept/09

2.7.0 before week 1 of development

When we make fixes on the trunk before week 1 of development begins.

Development Team

2.7.0.1

10/Sept/09

2.7.0 week 1 of development

Week 1 demo on Test.

Development Team

2.7.0.2

17/Sept/09

2.7.0 week 2 of development

Week 2 demo on Test.

Development Team

2.7.0.3

24/Sept/09

2.7.0 week 3 of development (functional testing candidate)

Week 3 demo on Test. This is the feature freeze version. Any feature at this point that is deemed not ready during fucntional testing is either bumped from the release before regression begins or additional fixes are going to have to be made and another release deployed to test.

Development Team

2.7.0.4

29/Sept/09

2.7.0 initial regression testing candidate

This is the code freeze version deployed to test for regression testing. Only blockers and very low risk issues should be fixed at this point.

Development Team

2.7.0.5

01/Oct/09

2.7.0 second regresstion testing candidate

Let's say we fixed a few issues, built one or more times on integration, re-deployed to test for testing those fixes as well as some re-regression but found a few more issues to be resolved.

Development Team

2.7.0.6

05/Oct/09

2.7.0 initial staging release candidate

Let's say we fixed a few more issues, built one or more times on integration, re-deployed to test for testing those fixes as well as some re-regression and did not found any more issues to be resolved. We now have a build to hand over to the deployment team for deploying to staging.

Development Team

2.7.0.7

17/Nov/09

2.7.0 second staging release candidate

Let's say we fixed a few issues, built one or more times on stage build, re-deployed to staging for testing those fixes but found a few more issues to be resolved.

Deployment Team

2.7.0.8

24/Nov/09

2.7.0 production release candidate

Let's say we fixed a few more issues, built one or more times on stage build, re-deployed to staging for testing those fixes and did not found any more issues to be resolved. We now have a build for deployiong to production. That means that 2.7.0 is actually 2.7.0.8, but we just drop the build minor and refer to 2.7.0.8 as 2.7.0.

Deployment Team

2.7.1

08/Dec/09

2.7 first patch release

This is the parent version for all 2.7.1.X versions. It encompasses everything that is in the first 2.7 patch production deployment.

Deployment Team

2.7.1.0

03/Dec/09

2.7 first patch release, first build to staging

Let's say we fixed a few issues, built one or more times on stage build, re-deployed to staging for testing those fixes but found a few more issues to be resolved.

Deployment Team

2.7.1.1

04/Dec/09

2.7 first patch release, second build to staging

Let's say we fixed a few more issues, built one or more times on stage build, re-deployed to staging for testing those fixes and did not found any more issues to be resolved. We now have a build for deploying to production.

Deployment Team

2.7.1

15/Dec/09

2.7 BAU

This is not another version in Jira, it is just listed to highlight the fact that if all we are going to release for a BAU is configuration changes, but no new artifiacts, we just assign the fix version of those Jira issues to the version that is currently on production.

Deployment Team

2.7.2

22/Dec/09

2.7 second patch release

This is the parent version for all 2.7.2.X versions. It encompasses everything that is in the second 2.7 patch production deployment.

Deployment Team

2.7.2.0

17/Dec/09

2.7 first patch release, first build to staging

Let's say we fixed a few issues, built one or more times on stage build, re-deployed to staging for testing those fixes and did not found any more issues to be resolved. We now have a build for deployiong to production.

Deployment Team

Version Maintenance


Responsibility

Version Creation
  • The development team will manage the creation of versions in Jira during the development phase (everything up until there is an initial staging release candidate on Test). This responsibility is currently held by ABC.
  • The deployment team will manage the creation of versions in Jira during the deployment phase (everything after the deployment team hands off an initial staging release candidate for staging), all production patches, and all production BAUs. This responsibility is currently held by XYZ.
Assigning Affects and Fix Versions to Jira Issues
  • Affects Version is set by the Reporter of the issue. This field should only be specified for issues with an Issue Type of Bug. If the issue occurs on production, make sure to set the Affects Version to the version on production. If the issue occurs on Test and/or Staging, make sure to set the Affects Version to the build on Test and/or Staging (this can typically be found in the banner message). If the issue occurs on both Production as well as Test and/or Staging, set the Affects Version to both the version on Production as well as the version on Test and/or Staging. For questions, please ask ABC.
  • Fix Version can be set by the Reporter of the issue during issue creation if known ahead of time, but is typically set by the Assignee of the issue when resolved. When the Fix Version is set during creation, specify a build major (ex., 2.7.4) but not a build minor (ex., 2.7.4.1). When the issue is Resolved, the Assignee sets/updates the Fix Version to the build minor of the next build to Test or Staging (ex., 2.7.4.1). The Assignee should work with the Build Manager to help determine whether or not the resolution will make it into the next Test/Staging build before setting/updating the Fix Version. For questions, please ask ABC.
  • ABC is responsible for making sure the Affects Version and Fix Version is properly specified when issues are created during the development phase. The Build Manager is responsible for working with ABC before deploying a build to Test to make sure the Jira Issues making it into that build are accounted for and have the correct Fix Version.
  • XYZ is responsible for making sure the Affects Version and Fix Version is properly specified when issues are created during the deployment phase. The Build Manager is responsible for working with XYZ before deploying a build to Staging or Production to make sure the Jira Issues making it into that build are accounted for and have the correct Fix Version.

Version Lifecycle

Step 1: Create the Version

The first step in a versions life is obviously being created. If you don't know the release date, then just specify it when it is determined. It can always be changed later, but if you know it please add it since it is a required field before releasing the version and also allows the release to show up as an event on your project's calendar.

Let's create the next 2.7 production patch.

Step 2: Make Master-Nested Version Associations

For each build major (ex., 2.7.1), you must go to the Planning Board for the Connect Project and mark it as a master version for each build minor nested version. (ex., 2.7.1.0, 2.7.1.1). To do so, make sure Versions is selected in the dropdown in the right-hand column, find each nested version, click the pencil next to where it says "Master: None", and choose the parent version.

Let's create the master-nested version relationship with 2.7.3 and 2.7.3.0.

Once you have done this for each nested version, make sure to synchronize the fix versions (in case nested versions had been assigned to a fix version before they were associated with a parent version) by clicking on the double arrow icon to the right of the Versions dropdown in the right-hand column.

Step 3: Merge Versions

When a production release candidate has been identified, it is time to merge the nested versions into the master version. The nested versions, each with a different build minor, have importance during development and deployment phase, but once released to production all we care about is the master versions, identified by a different build major.

For example, when we are ready to release 2.7.4, merge 2.7.4.0 and 2.7.4.1 into 2.7.4.

Step 4: Release the Version

When a release is deployed to production, release the version in Jira.

For example, if we release 2.7.2 on Dec 22, release that version in Jira on that date.

Step 5: Archive the Version

Once we release a new version major to production, the soak period has ended, and there is no going back, the previous versions can be archived. It doesn't actually do much, but unclutters some of the version dropdown menus throughout Jira, making it easier to assign values to those drop-down menus. You can always unarchive if you need to for some reason.

It's been a few weeks since we released 2.7, so let's archive 2.5.