Developer Area/Version Numbering Policy: Difference between revisions

Latest revision as of 13:56, 26 November 2014

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

From 15.04 on

Starting with the Mahara 15.04 series (in April 2015), Mahara releases will be numbered YY.MM.Z, for example, "15.04.0".

The "YY.MM" portion of the version number is the major version or series. It encodes the year and month that the series is scheduled to be released. 15.04 = April 2015. Mahara releases a new major version every 6 months, in April and October, so this will increment as follows: 15.04; 15.10; 16.04; 16.10; etc.

The "Z" portion of the version number is the minor version or point release. It starts at 0 and is incremented with each minor release for a series. Minor releases are released on an as-needed basis, and not by any predetermined schedule. These will increment like so: 15.04.0; 15.04.1; 15.04.2; etc.

1.10 and earlier

The Mahara 1.10 series was the last to use the older Mahara release numbering system. Under this system, Mahara major releases were numbered 1.7; 1.8; 1.9; 1.10; etc. And minor releases were numbered 1.2.0; 1.2.1; 1.2.2; 1.2.4; etc.

How the Version Number changes in git

The Mahara version number is reflected in git branch names, git tag names, and in the $config->release variable of Mahara's htdocs/lib/version.php file.

Stable branch

Imagine the current stable version is 15.04.6. The htdocs/lib/version.php file will have this version number:

In the Launchpad download package: "15.04.6"
In the git commit tagged as 15.04.6_RELEASE: "15.04.6"
In the HEAD commit of the 15.04_STABLE branch: "15.04.7testing"
- Bug fixes will be made from time to time here.

When the release 15.04.7 is ready:

The htdocs/lib/version.php in the 15.04_STABLE branch will be updated to say "15.04.7"
This commit will be tagged as 15.04.7_RELEASE
This commit will be packaged and uploaded to Launchpad
The htdocs/lib/version.php in the 15.04_STABLE branch will be updated again, to say "15.04.8testing"

Dev branch

Meanwhile, the master git branch will be preparing for the next major version, 15.10. So...

In the master git branch, lib/version.php file will contain the version "15.10.0dev"
This won't change until we're reading to release the first 15.10 release candidate.

When we release the first 15.10 release candidate...

We'll make a new branch 15.10_STABLE, based off of master
The lib/version.php in the master branch will be bumped to the next major release, "16.04.0dev"
The lib/version.php in the 15.10_STABLE branch will be bumped to "15.10.0rc1"
- When 15.10.0 is ready, this branch will update as per the instructions in the "Stable branch" section above.

Version bumps and database upgrades

Mahara also has an internal version number, also known as the database version. This version number is stored in the htdocs/lib/version.php file in $config->version. It is not meant to be human readable, but is used by the program to determine what code to run when upgrading.

The database version has the format YYYYMMDDZZ, where "YYYYMMDD" is the current date, and "ZZ" is an arbitrary counter that starts at 00.

On a stable branch, the "YYYYMMDD" should always remain the same, and only the "ZZ" should be incremented with each upgrade.
On the master branch, the current date should be used and "ZZ" should be "00" unless there are multiple updates pushed on the same day.
- 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 backport a database upgrade from one branch to another:

Make sure to update the version number so that it matches each branch!
Make sure that the upgrade is safe to run multiple times!
- Because a user who upgrades from an older branch to a newer branch, will wind up running your upgrade twice.

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.

@@ Line 3: / Line 3: @@
 <div id="section_1">
-==Stable/Unstable Versions==
+===From 15.04 on===
-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.
+Starting with the Mahara 15.04 series (in April 2015), Mahara releases will be numbered '''YY.MM.Z''', for example, "15.04.0".
-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.
+The "YY.MM" portion of the version number is the '''major version''' or '''series'''. It encodes the year and month that the series is scheduled to be released. 15.04 = April 2015. Mahara releases a new major version every 6 months, in April and October, so this will increment as follows: 15.04; 15.10; 16.04; 16.10; etc.
-Like Debian, Ubuntu and some other software, Mahara releases have code names, as documented in the [[Developer Area/Release Policy|release policy]].
+The "Z" portion of the version number is the '''minor version''' or '''point release'''. It starts at 0 and is incremented with each minor release for a series. Minor releases are released on an as-needed basis, and not by any predetermined schedule. These will increment like so: 15.04.0; 15.04.1; 15.04.2; etc.
-<div id="section_2">
+===1.10 and earlier===
-===Stable===
+The Mahara 1.10 series was the last to use the older Mahara release numbering system. Under this system, Mahara major releases were numbered 1.7; 1.8; 1.9; 1.10; etc. And minor releases were numbered 1.2.0; 1.2.1; 1.2.2; 1.2.4; etc.
-Stable versions are numbered YY.MM.Z. The "YY.MM" version is the "series" or "major version". A new major version of Mahara is released every 6 months, and the YY.MM is the Year and Month of the release. For instance version 15.04 will be released in April 2015. The "Z" is the "minor version", which will b where YY and MM are the year and month that the version is scheduled to be released, and Z is a nu. As of the writing of this section, Mahara is at <code><font face="Verdana,Sans-Serif">1.0.6</font></code>, this version number will be used for the examples that follow.
+==How the Version Number changes in git==
-</div><div id="section_3">
+The Mahara version number is reflected in git branch names, git tag names, and in the <code>$config->release</code> variable of Mahara's <code>htdocs/lib/version.php</code> file.
-===Unstable===
+=== Stable branch ===
-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".
+Imagine the current stable version is 15.04.6. The <code>htdocs/lib/version.php</code> file will have this version number:
+* In the Launchpad download package: "15.04.6"
+* In the git commit tagged as <code>15.04.6_RELEASE</code>: "15.04.6"
+* In the HEAD commit of the <code>15.04_STABLE</code> branch: "15.04.7testing"
+** Bug fixes will be made from time to time here.
-</div></div><div id="section_4">
+When the release 15.04.7 is ready:
+* The <code>htdocs/lib/version.php</code> in the <code>15.04_STABLE</code> branch will be updated to say "15.04.7"
+* This commit will be tagged as <code>15.04.7_RELEASE</code>
+* This commit will be packaged and uploaded to Launchpad
+* The <code>htdocs/lib/version.php</code> in the <code>15.04_STABLE</code> branch will be updated again, to say "15.04.8testing"
-==How the Release Version Changes==
+=== Dev branch ===
-=== Stable branch ===
+Meanwhile, the <code>master</code> git branch will be preparing for the next major version, 15.10. So...
+* In the <code>master</code> git branch, <code>lib/version.php</code> file will contain the version "15.10.0dev"
+* This won't change until we're reading to release the first 15.10 release candidate.
-Imagine the current stable version is 15.04.6. This version number will be present in the <code>lib/version.php</code> file in the git commit tagged with <code>15.04.6_RELEASE</code>, and it will also be in the download package on Launchpad. In the HEAD commit of the <code>15.04_STABLE</code> branch, <code>lib/version.php</code> will contain '15.04.7testing'. Bug fixes will be made from time to time here.
+When we release the first 15.10 release candidate...
+* We'll make a new branch <code>15.10_STABLE</code>, based off of <code>master</code>
+* The <code>lib/version.php</code> in the <code>master</code> branch will be bumped to the next major release, "16.04.0dev"
+* The <code>lib/version.php</code> in the <code>15.10_STABLE</code> branch will be bumped to "15.10.0rc1"
+** When 15.10.0 is ready, this branch will update as per the instructions in the "Stable branch" section above.
-At the point when a release is ready, the version in <code>lib/version.php</code> will be changed to 15.04.07, the release made and the version changed again to <code>15.04.08testing</code>.
+==Version bumps and database upgrades==
-=== Dev branch ===
+Mahara also has an internal version number, also known as the '''database version'''. This version number is stored in the <code>htdocs/lib/version.php</code> file in <code>$config->version</code>. It is not meant to be human readable, but is used by the program to determine what code to run when upgrading.
-Meanwhile, the <code>master</code> git branch will be preparing for the next major version, 15.04. So, its <code>lib/version.php</code> file will contain the version <code>15.10.0dev</code>. When we branch for 15.10, we'll create the 15.10_STABLE branch, and the <code>lib/version.php</code> on that branch will be changed to 15.10.0rc1, while <code>master</code> will be bumped to 16.04.0dev
+The database version has the format <code>YYYYMMDDZZ</code>, where "YYYYMMDD" is the current date, and "ZZ" is an arbitrary counter that starts at 00.
-==Version bumps and database upgrades==
-In <code>lib/version.php</code> (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.
+* '''On a stable branch''', the "YYYYMMDD" should always remain the same, and only the "ZZ" should be incremented with each upgrade.
+* '''On the master branch''', the current date should be used and "ZZ" should be "00" unless there are multiple updates pushed on the same day.
+** 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.
+'''If you backport a database upgrade from one branch to another:'''
+* Make sure to update the version number so that it matches each branch!
+* Make sure that the upgrade is safe to run multiple times!
+** Because a user who upgrades from an older branch to a newer branch, will wind up running your upgrade twice.
-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.
+'''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 <code>make push</code>, the precommit checks will run the script <code>test/versioncheck.php</code>, which will test for some common version numbering mistakes.