To install a specific version of Open edX using tutor it is necessary not only to know the correct edx-platform GitHub tag that corresponds to the named release, but also the precise PyPi release of tutor that will yield an openedx container built with the corresponding named release. I found this unintuitive until after having delved deeper into tutor’s source code. Namely, how its openedx Dockerfile is templated. The short story is that any given version of tutor will build an openedx container for an exact named release of edx-platform. If, for example, you want to build-deploy a platform that runs exactly “open-release/nutmeg.3” then you need to do this with the exact version of tutor that will yield an openedx container of this edx-platform release.
The tutor maintainers are objectively disciplined about how their major version number increments. For example, version 15.x of tutor strictly corresponds to “Olive”, which is the 15th release of Open edX. On the other hand, edx-platform’s version naming convention has evolved over time and thus is less consistent over the life of the project. Moreover, each named release includes minor release such as “open-release/nutmeg.1” and “open-release/nutmeg.2” and so on. Finding which version of tutor yields which minor release of Open edX is, well, tedious.
Further complicating matters is that some of my clients refer to Open edX by it’s version number, as does the official Open edX documentation on occasion. For example, Nutmeg is described as the 14th community release of Open edX while in point of fact it’s actual version number is 0.13.
A final potential stumbling block for some might also be that edx-platform uses a system of similarly named branches and tags. For example, there is a branch named “open-release/nutmeg.master” which, to my understanding, contains the interim commits between minor releases.
To hopefully make this all simpler for everyone, I created the following table this afternoon through a forensic deep dive of the tags in both edx-platform as well as tutor
In the event that i’ve gotten anything wrong, feel free to modify and repost the chart image using this editable Excel spreadsheet. edx-platform-tags.xlsx (9.8 KB)
I think this chart is very helpful, especially for beginner tutors who are not sure about which version and release name as well.
so if u should add it to the official tutor docs that can help a lot.
I think this is a small part of a larger topic, about migrating legacy native builds to tutor, which is something that I’m increasingly being hired to do for clients. I’m at work on two such projects right now.
I think tutor’s readthedocs might already have a page about migrating to tutor from native, and if so then this material would be an excellent addition.
Yes, I also regularly receive requests on this topic, though I have never performed such a migration myself. I would love to have better docs on migration from native, but so far no one has contributed any. Would you like to submit a tutorial?
I don’t know about the issue of setup.py, it’s probably a missed step while making a release, in any case I am not sure how/if the metadata in that file are used
One more comment on this topic: tutor provides a setting OPENEDX_COMMON_VERSION that you can use to pin your build-deploy to a specific edx-platform release. Try to avoid using this. For me this frequently results in failed builds due to hard-to-understand stack traces.
tutor does a good job selecting the release and so you’re usually better off adjusting the version of tutor and then letting it take care of the specifics about any edx code repositories.
Here’s an illustrative example. In this case the Dockerfile includes references to git commits that only exist in certain edx-platform branches, tags and releases. The tutor maintainers had this knowledge at the point in time that they cut a certain release of tutor, and they set the tutor defaults accordingly. In this example i override tutor’s v14.2.4 default value of OPENEDX_COMMON_VERSION to a benign seeming value of open-release/nutmeg.3 which apparently lacks these commits.
