How to manage versioning in GitHub

Owned by Burke Mamlin
Last updated: Aug 14, 2015
3 min read

There are several approaches to managing versioning of software. This page will describe how OpenMRS manages its versions. This approach has worked well for us, so we have adopted it for many modules and recommend that you consider adopting this approach for your code as well.

If you are planning to release a new version of a module, you will probably want to read the Releasing a New Version of a Module page.

We use major, minor, and maintenance versions as described on the Versioning page. Within our GitHub repository, we use version branches and tags as follows:

Version Tags

By convention, tags are used to specify releases and are named using the release version number. For example, when the code for version 2.1.1 is ready to be released, it is tagged with a name like "2.1.1".

Version Branches

Whenever the code is ready to be released as a new minor (or major) version, a version branch is created for that version of the code. For example, when 2.1.0 is ready to be released, it is tagged as "2.1.0" and a branch named "2.1.x" is created. This branch is used for any subsequent maintenance releases for that minor version.

Conventions Followed

  • Development always occurs on the master branch. We never develop directly on a version branch.
     
  • When any bug fixes are desired for a previously released version, those changes are made within master and then backported to any version branch(es) of the prior version(s) to get the bug fix.

Versioning Workflow

Releasing a new major or minor version

When code in the master branch is ready to be released as a new major or minor version, it is tagged, a version branch is created, and then the version within master is advanced to the next minor version.

For example, imagine that you want to release master as version 2.1.0.

  • Set version on master to "2.1.0"
  • Create a tag named "2.1.0"
  • Branch master to "2.1.x"
  • Advance the version within master to "2.2"

Daily Development

All day-to-day development is done within master. Any bug fixes to be applied to prior releases are first committed and tested within master and then backported to the appropriate version branch(es).

Maintenance Releases

When a bug fix is needed for a prior version of the code, the fix is committed and tested within master. Then the changes for that bug fix are backported to the appropriate version branch(es) and, when a new maintenace version is ready to be released, the version branch is tagged as the maintenance release.

For example, imagine master is at 2.2 and you find a bug in 2.1.0 and want to release a fix as 2.1.1:

  • The bug is fixed and tested within master.
  • The changes are then backported (applied to) the 2.1.x branch.
  • The version of the 2.1.x branch is advanced to "2.1.1".
  • The 2.1.x branch is tagged as "2.1.1".

Sometimes a single bug fix will merit a new maintenance release. In most cases, multiple bug fixes are backported to a version branch before a new maintenance release is tagged.

Supported Versions

By convention, OpenMRS supports the past three minor versions. This means that we will continue to backport bug fixes to version branches for these supported versions. When a version is no longer supported, then we stop backporting bug fixes or performing maintenance releases for that version.

For example, imagine that you just released version 2.1.0 and have announced that version 1.8.x is no longer supported. When a bug is later fixed, that fix would be backported to the 2.1.x, 2.0.x, and 1.9.x version branches, but would not be backported to the 1.8.x branch.