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 Lilac, @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 lilac branch.
  • Build all the tutor images locally (as they are not available from docker.io): tutor config save && tutor images build all.
  • Install the plugin from source as well, and checkout a branch dedicated to the upgrade: git checkout -b username/lilac.
  • Enable the plugin.
  • In the plugin’s setup.py, bump the “tutor-openedx” version that the plugin depends on.
  • In the __about__.py module, bump the version number to the next major release (in our case: “v12.0.0”).
  • Replace all instances of the previous release name (“koa”) by the new one (“lilac”) in the entire repo: git grep -i koa.
  • 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 (v12 for nodejs and v3.8 for Python in Lilac). 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 (2021-06-08T22:00:00Z for Lilac).

2 Likes