Open edX Release FAQ

Owned by Ned Batchelder (Deactivated)
Last updated: Dec 13, 2023 by Kyle McCormick
5 min read

What is an Open edX release?

Periodically, we tag our repos as an official Open edX release. Releases are named alphabetically with tree names. Aspen was released in September 2014; Olive was released in December 2022. After Olive was Palm, and so on.

Details of the release schedule are at https://openedx.atlassian.net/wiki/spaces/COMM/pages/3613392957.

The history is here: https://edx.readthedocs.io/projects/edx-developer-docs/en/latest/named_releases.html

 

Why do we make Open edX releases?

  • The Open edX community can share knowledge and improvements more easily when many people use the same stable, consistent version of the Open edX code.

  • Open edX releases create milestones that are easier to talk about and use than the ever-shifting master branches.

  • It creates a good cadence for a period of pre-release testing and bugfixing.

  • It creates a reliable upgrade cadence for site operators to follow.

Is it OK that some people use master?

It's great that some in the community are following master. This gives us an earlier indication of the code's stability and fitness, and makes it easier for them to contribute code to us.

We want to make it easier for people to use master if it is right for their business.

Who makes the Open edX releases?

The Build - Test - Release working group is in charge of Open edX releases. If you have questions about the group, the process, or getting involved, reach out in their Slack channel or in their forum subcategory.

Ned Batchelder (ned@edx.org, or @nedbat on Slack) used to be the release manager, and helps the group now with logistical issues. Ned can also be the point of contact for internal 2U/edX people with questions.

When do we make Open edX releases?

We make a release every six months. In the past (pre-Juniper), releases have had to wait for an important change in the code, but we are focusing on date-based releases now. See the release schedule for details.

The Support Windows spreadsheet shows interactions among the supported versions of our dependencies.

What is in an Open edX release?

This is an ambiguous question. When ask about something “being in the Open edX release,” we need to be more specific. There are a few levels at which code/features can be in a release….

Tagged Repositories

Each release, we create a release master branch and release tags in various repositories. For example, in Nutmeg, we created the open-release/nutmeg.master branch for testing, followed by one tag for each point release: open-release/nutmeg.1, open-release/nutmeg.2, open-release/nutmeg.3. We made those tags in these repos:

edx/edx-e2e-tests edx/frontend-app-communications edx/frontend-app-ora-grading edx/testeng-ci openedx/blockstore openedx/configuration openedx/course-discovery openedx/credentials openedx/cs_comments_service openedx/devstack openedx/ecommerce openedx/ecommerce-worker openedx/edx-analytics-configuration openedx/edx-analytics-dashboard openedx/edx-analytics-data-api openedx/edx-analytics-pipeline openedx/edx-app-android openedx/edx-app-ios openedx/edx-developer-docs openedx/edx-documentation openedx/edx-notes-api openedx/edx-platform openedx/enterprise-catalog openedx/frontend-app-account openedx/frontend-app-authn openedx/frontend-app-course-authoring openedx/frontend-app-ecommerce openedx/frontend-app-gradebook openedx/frontend-app-learner-record openedx/frontend-app-learning openedx/frontend-app-payment openedx/frontend-app-profile openedx/frontend-app-publisher openedx/frontend-app-support-tools openedx/frontend-template-application openedx/license-manager openedx/openedx-demo-course openedx/repo-tools openedx/tubular openedx/xqueue

These branches and tags help us coordinate testing, documentation, and bug fixes. They are used as input to the community deployment tools, like Tutor. However, a repository being tagged doesn’t always mean its features are fully supported. More on that later.

To be tagged, a repository must be in the openedx GitHub organization. In order get a repository moved into the openedx organization, you can file an Axim request. It can then opt in to being tagged by including openedx-release: "<BRANCH-TO-RELEASE>" in their openedx.yaml file, where <BRANCH-TO-RELEASE> is typically set to master or main.

Dependent Repositories

Only top-level repositories should be tagged.

The top-level repositories inevitably depend on various dependent repositories (i.e., Open edX libraries). We do not put tags in libraries. Instead, the top-level repositories use setup.py and/or package-lock.json to specify the which library versions they need. Different top-level repositories may need different versions of the same package.

More details are in OEP-10: Open edX Releases.

Features: Default, Supported, Experimental, and Unsupported

Tagged repositories include various features. The exact definitions are still fuzzy, but the release notes generally group these features into four tiers:

  • 1. Default features. These features are enabled out-of-the-box when someone installs Open edX using the supported community deployment tool (as of Quince, that’s Tutor). The Build-Test-Release WG treats these features as the highest priority for testing, bugfixing, and security.

  • 2. Supported features. These features may be off by-default, but the community still tests them, tries to keep bug-free, and monitors their security. The community deployment tool usually makes it easy to turn these features on (for example, there may be an official Tutor plugin available).

  • 3. Experimental features. These features are moving towards being Supported, but aren’t quite there yet. Site operators can turn them on in order to get a preview of what’s coming in future releases. Bug reports are appreciated, but may not be high priority.

  • 4. Unsupported features. Tagged repositories sometimes include features that the community no longer supports, or never supported. This includes features which are deprecated but haven’t yet been removed. Site operators can turn these on, but should not expect bugfixes or security patches from the community

What tags and branches are used in a release?

A release is started with a "release master" branch, which will be named "open-release/zebrawood.master" (for the fictitious Zebrawood release.) Once that branch is created, fixes are applied to it to stabilize the release. The first official release will be a tag "open-release/zebrawood.1" on that master branch. More fixes can be applied, leading to a "open-release/zebrawood.2" tag. As the rate of fixes slows, we stop making tags, and instruct people to install from the tip of the "open-release/zebrawood.master" branch.

Occasionally we will create testing branches, for example "open-release/juniper.alpha1". This is not the start of the Juniper release. This is a snapshot branch for testing by the community during a long gap between releases.

How do we make a release?

The detailed instructions for making release branches and tags is at https://openedx.atlassian.net/wiki/spaces/COMM/pages/19662426

What is the timeline for a release?

Once the release master branches are created, there's a testing period of about 6 to 8 weeks. During that time, the community will be testing the release. Engineers should be on the lookout for fixes being applied to master that might need to be cherry-picked into the release.

The release manager may also get in touch with you for help diagnosing or fixing a problem with the release. The release manager understands these kind of unplanned injections are difficult, and appreciates any help you can give. Work with your team’s leadership to balance this against your other work.

How long are releases supported?

An Open edX release is supported until the next release is official. We only support the latest release.

Support includes applying fixes that address security or data-loss problems. We do not provide formal help with how to install, run, or customize installations. The community is self-supporting at https://discuss.openedx.org.

How do I add to the release notes?

In the months leading up to a release, we keep a running wiki page for engineers to leave notes about changes. See the child pages under https://openedx.atlassian.net/wiki/spaces/COMM/pages/13205845 .

How do I make a fix in a release?

Usually, fixes for a release are changes that have been made to master that are then cherry-picked verbatim onto the release master branch. If you have a fix you want applied to a release, you can do it two different ways:

  1. You can make a pull request against the release master branch (for example open-release/koa.master) and go through the usual review-and-merge process. In that pull request, please indicate what fix on master it duplicates.

  2. Let the release manager know about the fix, and they will do the cherry-picking.

Sometimes, a fix needs to be different than what is on master. In that case, make a pull request into the release branch with a detailed description of why it is different than the master branch.

See “Who Makes the Open edX Releases” above for getting in touch with the release manager.

What installation methods do we support?

We support two installation methods: devstack for development work, and Tutor, a Docker-based installation suitable for production. Our support for them includes ensuring that they will successfully install. We don't offer direct support for using either environment. The community is self-supporting in Slack and Discourse: https://openedx.org/getting-help has links.