Developer Area/Release Instructions/Major Release

From Mahara Wiki

< Developer Area‎ | Release Instructions

Here are the things to do before and after running through the usual release instructions when preparing a new major release.

BEFORE the release

Release candidate

Major releases should be preceded by at least one release candidate.

Creating the new branch

The new branch should have been created as part of the first RC release. If it wasn't, then do it now. See the instructions under the Release Candidate page.

Update the Readme file

Review the readme file and update it to reflect any changes, in particular around versions of PHP, Postgres, and MySQL / MariaDB supported and the minimum browser requirements. These need to be stated clearly.

For PHP versions, the minimum and maximum supported version needs to be listed to avoid confusion as PHP does release versions more frequently.

Write the Change log & Release notes

You'll need to write up the Change Log beforehand at least because it gets included in the release's ZIP file. It should include any information about backwards compatibility breaking.

Example for release notes

Mahara 21.04.0 Release Notes

This is a stable release of Mahara 21.04. Stable releases are fit for general use. If you find a bug, please report it to the tracker:

This release includes an upgrade path from 18.04.0. If you wish to upgrade, we encourage you to make a copy of your website and test the upgrade on it first, to minimise the effect of any potential unforeseen problems.

Changes from 20.10:

New features:

Delete all pages within a collection when a collection is deleted Exclude group tutors and admins from showing under "Members without a submission to the group" New submissions plugin Turn peer role into a configurable role so it can see content Improvements to the Mahara docker environment Trigger off fast_index.php when reindexing the site with elasticsearch Create a default option for comments on the 'Note' block and for pages Granular options which portfolios to see in 'Latest changes I can view More useful information on the 'Portfolio completion' overview page Restrict with how many people or groups of people you can share your portfolio with New 'Portfolio review' block A person can remove access to a portfolio shared with them Report: Completion and review Report: Reviewer summary Report: Portfolios with a reviewer Show student ID as part of the display name function Added portfolio creation queue for institution templates Group administrator be allowed to see group submission archive for their group

Example for changelog

Bug 1900786: combined exports: timing issues causing leap2a to be put into the wrong directory Bug 1902146: SmartEvidence framework Institution "All" option cannot be saved in non-English Bug 1902679: Add confirmation step for deleting an external app Bug 1903205: Only show Account migrate link if migration is possible Bug 1903620: Access list needs to retain the sorted list of people Bug 1904352: Adding navigation block to a collection can cause loss of data

AFTER the release

Bump the stable_version on

This should now be done automatically via the htdocs/admin/cli/create_version.php script which is controlled by cron and will update once a day.

If during major upgrade you can't wait for the cron you can log into the server and run the CLI script manually, eg

sudo -u www-data php create_version.php

If that is failing you can always do it the old way - see below

OLD INFO - should not need to do this any more

This is what sets the right download link in the header. And also sets the 'Latest version' info on the Mahara Administration dashboard for "Site information"

To do this you need to do 2 things:

1) Edit the htdocs/local/upgrade.php file and add a upgrade block, eg:

 if ($oldversion < 2018102500) {
    set_config('mahara_stable_version', '18.10');

2) Edit the htdocs/local/version.php file and change the version and release variables, eg:

 $config->version = 2018102500;
 $config->release = '18.10.0';

Note: Deploying the change to testing site will not show change - only deploy to production will

Generate the git stats

The git contributor stats go in the release announcement on the Mahara News forum. Grab our version of gitdm from the mahara-scripts repo:

git clone [email protected]:scripts/mahara-scripts.git

Because the master and latest _STABLE branch run in parallel during RC time we need to find the last commit by name before the previous .0 release and then find that same commit by name and copy it's commit ID and then replace [commit ID] below with the correct value and here is how to generate the stats at the end:

cd ~/path/to/mahara.git
git log -p -M --no-merges [commit ID]..21.04_STABLE > ~/mahara.log
cd ~/code/mahara-scripts/gitdm/
cat ~/mahara.log | ./gitdm -c mahara.config -u -s -z -o results -h results.html

Have a look at the results text file to ensure that developers are only listed once (otherwise add them to the mahara.aliases file). Also make sure that there is no "(unknown)" company by making sure that all of the necessary mappings are in mahara.domain-map. If there are "(unknown)" company results, look through the generated text file "database.dump" to locate the unmapped individuals/emails.

Launchpad series

When releasing 1.4, we did the following:

  • Changed the status of 1.5 to "Active development" and the description to "Future release of Mahara"
  • Changed the status of 1.4 to "Current stable release" and the description to "Stable release of Mahara"
  • Changed the status of 1.3 to "Supported" and the description to "Old stable release of Mahara"
  • Changed the status of 1.2 to "Obsolete" and the description to "Old stable release of Mahara (no longer supported)"

Make sure to update both the Mahara and Mahara-Lang projects.

Mahara manual

When releasing a major version, the Mahara manual also needs some attention.

  • Remove the version that is now out of support from the quick links to older manuals.
  • Mention on the now unsupported manual that it is unsupported.
  • Change the sentence on the index page of the new release to include the release date and add a link to the release announcement.
  • Change the redirect in the index.html of the manual-builder package (Catalyst only).


There are a few places where the release should be announced:

  • Release notes posted in the News forum (copy the format from the release notes for the previous release).
  • post which will also immediately post to Twitter.
  • Any other places where you want to announce the release.