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 Open edX Release Schedule.

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 followed by 3+ release tags in various repositories. For example, in Nutmeg, we created these:

• Branch: open-release/nutmeg.master

• Tags: open-release/nutmeg.1, open-release/nutmeg.2, open-release/nutmeg.3.

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 exist to help the Build-Test-Release working group orchestrate their testing, documentation and fixes, and they are used as input to the community deployment tools, like Tutor. A repository being tagged doesn’t necessarily mean it’s well-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 our libraries, because those tags would often conflict with the library versions which top-level repositories specify in their requirements.txt and package-lock.json files.

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

Features: Default, Supported, Experimental, and Unsupported

The tagged repositories include various features. Some features are enabled by default, whereas others need to be toggled on or configured.

The release notes, roughly, mention four tiers of features:

• 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 Process to Create an Open edX Release

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 Open edX Release Planning .

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.