Skip to content

Preparing a new plugin major version for a new Moodle major version

Jump to bottom
Alexander Bias edited this page Jul 18, 2022 · 6 revisions

Preface

  • This step-by-step tutorial was built based on existing best practices. Please follow it as much as possible, but do not hesitate to diverge from the given steps if necessary for your particular plugin upgrade work. However, if you diverge in any way, please check always if this tutorial should be updated based on your scenario.

  • The given version numbers and URLs are for upgrading to Moodle 4.0. Please adapt your reading to future Moodle versions on-the-fly.

Backlog review

  • Review existing Github issues and evaluate if you want / should solve them before / within your upgrade work for the new major release.

  • Handle all necessary tasks which have been identified to be handled before the major upgrade. For example a bugfix which should be fixed in the current plugin version as well.

Technical upgrade preparation

  • Create an issue on Github for the upgrade work

    • The issue name should be something like 'Upgrade plugin to Moodle 4.0'.
    • This issue will be the place for discussions about the upgrade work
    • It will also be a public signal that the upgrade work is being done by you.

  • In the case that you do not have write permissions to the plugin's Github repository, create a fork of the repository on Github.

  • Create a working branch for the upgrade work which is branched from the master branch.

git checkout master
git branch issue-42-upgrade-to-400

Organizational upgrade preparation

  • Review the official release notes and check if there is anything which you have to consider within your upgrade work. Look particularly at:

  • Review the upgrade.txt files in the Moodle codebase and check if there is anything which you have to consider within your upgrade work.

    • Go to https://github.com/moodle/moodle/find/master
    • Search for upgrade.txt
    • Review the upgrade.txt file for the plugin type of the plugin which you want to upgrade
    • Additionally, review the upgrade.txt files for relevant APIs like lib/upgrade.txt, user/upgrade.txt, admin/upgrade.txt, or cache/upgrade.txt.

  • If your plugin is producing any UI components, have a look at 'theme/upgrade.txtas well and ideally do a diff of/theme/boostto get a feeling if recent changes intheme_boost` could affect the appearance of your plugin.

  • If your plugin has dependencies to any other plugins or has been created as a derivative of another plugin, review the changes / the diffs of the other plugin which have happened in the meantime to see if you have to consider anything within your upgrade work.

Upgrading the plugin

  • Checkout your working branch.
git checkout issue-42-upgrade-to-400

  • Modify .github/workflows/moodle-plugin-ci.yml

    • Upgrade the Moodle major branch: 
      -        moodle-branch: ['MOODLE_311_STABLE']
+        moodle-branch: ['MOODLE_400_STABLE']

  • Modify README.md

    • Upgrade the required version: 
      -This plugin requires Moodle 3.11+
+This plugin requires Moodle 4.0+

  • Modify version.php

    • Upgrade the required Moodle core version and the supported Moodle core version: 
      -$plugin->requires = 2021051700;
+$plugin->requires = 2022041900;
-$plugin->supported = [311, 311];
+$plugin->supported = [400, 400];
      where the required version number is set to the internal Moodle version number of the new Moodle major version which can be found in the Moodle releases list. Do not change the $plugin->version number and $plugin->release string yet.

  • Modify CHANGES.md

    • Add a new section which will hold the changelog of all changes until the next release: 
       Changes
 -------

+### Unreleased
+
+* 2022-07-12 - Prepare compatibility for Moodle 4.0.
+
 ### v3.11-r1

  • Commit these changes.

git commit -a -m 'Prepare compatibility for Moodle 4.0.'

  • Handle all necessary tasks which have been identified in the previous section to be handled during the major upgrade.

    • Don't forget to make individual CHANGES.md entries for these tasks
    • Don't forget to make individual commits for these tasks

  • Modify version.php

    • Upgrade the plugin version number and the release string: 
      -$plugin->version = 2021051700;
+$plugin->version = 2022071200;
-$plugin->release = v3.11-r1;
+$plugin->release = v4.0-r1;
      where the version number is set to the same number as $plugin->requires. Please note that following minor plugin updates will then just increment the last two digits of the version number just like Moodle core does.

  • Modify CHANGES.md

    • Update the heading for the release: 
      -### Unreleased
+### v4.0-r1

  • Commit these changes

git commit -a -m 'Release v4.0-r1'
  • Push your working branch to Github
git push origin issue-42-upgrade-to-400

  • Wait for the Github Actions run to finish.

    • Look at the Github Actions log
    • If there are any errors or problems reported in the Github Actions log, fix them and push the branch again to Github. This applies both for errors and problems which you have introduced with your recent changes and errors and problems which have be triggered by upstream changes in Moodle core.

  • While waiting for Github Actions to finish, do some manual tests of the upgraded plugin on a Moodle installation with the target Moodle core version. Especially have a look at the appearance of the plugin widgets as the design and styles are not covered yet by automated tests. If you see any weird UI components, please fix them. If you see any plugin functionality being broken, please fix it and add a new automated test to increase the test coverage for the broken functionality.

  • As soon as Github Actions is all-green and you are confident with your manual testing, you are ready to proceed.

  • In the case that you are working on a forked repository, you can now create a pull request and wait for the plugin maintainer to handle it. Afterwards, you are done now completely. Otherwise, if you are the plugin maintainer, you can go on and publish the release officially.

  • Merge your working branch into the master branch and push the master branch to Github.

git checkout master
git merge issue-42-upgrade-to-400
git push origin master
  • Delete your working branch locally and especially from Github
git branch -d issue-42-upgrade-to-400
git push origin --delete issue-42-upgrade-to-400
  • Create a release branch which is based on the masterbranch.
git checkout master
git branch MOODLE_400_STABLE
  • Tag the new release version in the release branch
git checkout MOODLE_400_STABLE
git tag v4.0-r1

The Git tag is used to publish the new release on moodle.org easily in the next step.

  • Adapt the Github actions badge after cutting the release branch
git checkout MOODLE_400_STABLE
sed -i 's/master/MOODLE_400_STABLE/' README.md
sed -i 's/master/MOODLE_400_STABLE/' README.md
# The sed command is run twice by purpose. Everytime you run it, it replaces the string 'master' with 'MOODLE_400_STABLE'. This will match twice in the Moodle Plugin CI line. The other possibility would have been to write a slightly more complicated sed command.
git commit -a -m 'Adapt GHA badge after cutting the release branch'
  • Push this release branch and its tag to Github as well.
git push origin MOODLE_400_STABLE
git push origin MOODLE_400_STABLE --tags

Releasing the new plugin release on moodle.org

Aftermath

  • Close the Github issue for the upgrading job, referencing the new published version.
Clone this wiki locally