Developer Area/Version Numbering Policy

This page documents the Mahara version numbering scheme, and how the version numbers of new releases are decided.

Stable/Unstable Versions

Mahara has a stable and unstable release. The stable release is what you should use for production Mahara installations. Stable releases do not change much, mainly receiving bug fixes.

Unstable releases are previews for what will be in the next major iteration of Mahara. You should not use unstable releases on production websites, but you are welcome to try them out to see what new features will be in the next release.

Like Debian, Ubuntu and some other software, Mahara releases have code names, as documented in the release policy.

Stable

Stable versions are numbered X.Y.Z. As of the writing of this section, Mahara is at 1.0.6, this version number will be used for the examples that follow.

Unstable

Unstable is defined as "The HEAD of the master git branch". It is generally signaled by either an increased X or Y in the version number. For example, when the latest stable version was 1.9.0, unstable was heading towards Mahara 1.10. Releases of unstable have version numbers that end in "dev", like "1.10.0dev".

How the Release Version Changes

Stable branch

Imagine the current stable version is 15.04.6. This version number will be present in the lib/version.php file in the git commit tagged with 15.04.6_RELEASE, and it will also be in the download package on Launchpad. In the HEAD commit of the 15.04_STABLE branch, lib/version.php will contain '15.04.7testing'. Bug fixes will be made from time to time here.

At the point when a release is ready, the version in lib/version.php will be changed to 15.04.07, the release made and the version changed again to 15.04.08testing.

Meanwhile, the master git branch will be preparing for the next major version, 15.04. So, its lib/version.php file will contain the version 15.10.0dev. When we branch for 15.10, we'll create the 15.10_STABLE branch, and the lib/version.php on that branch will be changed to 15.10.0rc1, while master will be bumped to 16.04.0dev

Version bumps and database upgrades

In lib/version.php (and plugin version.php files), the $config->version line is used to trigger database upgrades. On a stable branch, this number should only ever be incremented by one. On the master branch, the current date should be used. This will ensure that someone who has upgraded on a stable branch (e.g. from 1.4.0 to 1.4.2) will still have a $config->version less than the first upgrade on the 1.5 or master branches.

If you are pushing the same database upgrade to both master and to one or more stable branches, you should increment the $config->version by one on your patches for the stable branches, and use the current date on master. In this case you must also ensure that your upgrade will not fail, (and will have no effect) when it is run a second time, because it will be run when users do their stable upgrade, and again when the next major upgrade comes out.

Plugin versions are messier, and also complicated by the fact that Mahara's upgrade system upgrades core all the way before it begins upgrading plugins. This has potential to cause nasty problems. For example, a plugin upgrade could refer to a db column in a core table which gets removed from core before the plugin upgrade has a chance to run. This can sometimes be avoided by forcing plugin upgrades at points during a core upgrade. However, that will upgrade the plugin all the way before it continues the core upgrade, with the same potential issues! As a last resort, $config->minupgradefrom can be used to force all upgrades to stop at a certain fixed point before continuing, but this is a hassle for users.

If you push your code to gerrit using the command make push, the precommit checks will run the script test/versioncheck.php, which will test for some common version numbering mistakes.