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. Next is Palm.

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.

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. 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 edX people with questions.

When do we make Open edX releases?

We make a release every six months. In the past 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 included in an Open edX release?

Individual repos from the openedx GitHub organization decide if they are part of an Open edX release by including the "openedx-release" key in their openedx.yaml file. This is also how the repo indicates what branch should be used for releases.

Only main repos need to be tagged. Dependent repos, such as libraries pulled into another service as a dependency, are not tagged.

In the past, both the edx and openedx GitHub organizations were searched for repositories to tag. As of Palm, only repositories in the openedx organization are considered. In order get a repository moved into the openedx organization, you can file a Axim request.

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

The features in Open edX are whatever features are in the repos. Feature flags and toggles can be used to turn features on and off, and the default for those toggles might be different for edx.org and for the Open edX releases, but there isn’t a separate list of what features are going into the Open edX release.

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.