How to upgrade a Tutor plugin

When we upgrade from one Open edX release to the next, I usually need to upgrade all the officially-supported Tutor plugins from the overhangio org on Github. This time, with Nutmeg, @developers have volunteered to upgrade some of these plugins themselves. Thank you! :heart: To help them with this task, I will summarize the steps that I usually go through to perform these upgrades.

  • Install Tutor from source, from the release candidate branch: in our particular case, it’s the nutmeg branch.
  • Build all the tutor images locally (as they are not available from docker.io): tutor config save && tutor images build all.
  • In the plugin’s setup.py, bump the version of the “tutor” package that the plugin depends on.
  • In the __about__.py module, bump the version number to the next major release (in our case: “v14.0.0”).
  • Install the plugin from source, and checkout a branch dedicated to the upgrade: git checkout -b username/nutmeg.
  • Enable the plugin.
  • Replace all instances of the previous release name (“maple”) by the new one (“nutmeg”) in the entire repo: git grep -i maple.
  • Go through the Dockerfile templates and manually upgrade all the 3rd-party requirements that you can find (dockerize, ipdb, etc.). Sometimes it’s not desirable to upgrade some pieces of software: for instance node and python are expected to run a specific version. Those required version numbers are specified in the edx/configuration repo. (look for SERVICENAME_VERSION variables)
  • Make sure that the plugin images (if any) are built correctly: tutor images build all.
  • Make sure that the plugin can be correctly initialized: tutor local init --limit=pluginnname.
  • If you need to make some changes to the docker-compose*.yml files and patches, make sure to backport these changes to the k8s-* patches, for compatibility with Kubernetes.
  • Make sure that the plugins work correctly by doing some basic usage testing. Pay close attention to any log (warning or error) that come out of the plugin containers as well as the lms container.

Bonus points:

  • Get rid of all “TODO” statements in the plugin code (git grep TODO).
  • Fix issues from the plugin Github repo.

Once you are satisfied with the upgrade, create a single commit that includes all your changes and open a pull request on the plugin repository. As usual, try to include as much information as you can in the commit message. In particular, try to explain all the non-trivial changes that you had to make. Note that we will not merge your PR in the master branch before the actual Open edX release (2022-06-08T22:00:00Z for Nutmeg).

7 Likes

A post was split to a new topic: Can plugins be totally removed?

Nutmeg release notes

  • We should migrate all official plugins from v0 to v1. See the instructions here.
  • It is time that we migrate the lms.env.json/cms.env.json files to YAML. As a consequence, all patches in these files should be renamed.
  • npm install should be replaced everywhere by npm clean-install. See this issue for reference.
1 Like