An Open edX release is comprised of specific versions of many repos. The participating repos all exist in the openedx GitHub organization and are determined by examining the OEPcatalog-2 openedxinfo.yaml files in each repo. In other words, every repository that has an openedxcatalog-info.yaml file in its root may or may not participate in the release, depending on the contents of the file. In particular, this line needs to be present:

Code Block
openedx-metadata: annotations: openedx.org/release: {ref: master}"main"

Tags and Branches

The release will have a branch in each participating repo. This is the branch where releases are made. This branch is named "open-release/RELEASENAME.master", for example, "open-release/zebrawood.master". Specific versions will be tagged on that branch, like "open-release/zebrawood.1". The first version will be ".1", not ".0".

...

To make the process practically feasible, a tag_release.py script exists in https://github.com/edx/repo-tools . In short, on each run it will discover which repositories are eligible for a release by listing all repos in the configured organizations (the default is edx, edx-ops, and edx-solutions) and examining their respective openedxcatalog-info.yaml files. If a given repository is indeed eligible, the script will execute the requested branching or tagging operation on it.

...

The release manager is a position in the Build-Test-Release WG. As part of their position, they should be nominated for the Release Manager Core Contributor Role , and hopefully confirmed for the role, which allows them to be granted write permissions on every repository that is part of the release.

...

1. Prepare for the cut a week before it is scheduled….

1a.

...

Run the tag_release script; if it outputs “*** openedx/somerepo has openedx-release 'maybe', skipped” lines, then you should get in touch with the repo owners and ask them if they should be included in the release. If yes, then the maybe: true line should be removed from the openedx.yaml file in the repo.
(see for instance this pull request).

1b. Schedule a release ceremony

Schedule a meeting for the day of release, including:

...

Schedule a release ceremony

Schedule a meeting for the day of release, including:

The release manager (you!)
At least one other Build-Test-Release WG member to check your work, take notes, etc.
If necessary, someone from Axim to grant permissions (see “Overview / Release Manager Permissions” section).
Anyone else who wants to listen in!

...

1b. Pre-announce the master branches

Make a post like this one in Discourse to let people know that the master branches will be created.

Get a 2U person to poke engineers inside 2U about it too.

...

1c. Create a wiki pages for release process notes

Create a child of this page for your own notes: Open edX Release Manager Notes

...

The repo-tools repo has a script, tag_release.py, to branch and tag the proper repos. The repos are indicated by an "openedx-.org/release" entry in their openedxcatalog-info.yaml file. Releases before Ficus would mark dependent repos (those installed by other repos, such as XBlock being installed by edx-platform). We no longer branch or tag dependent repos.

...

The branch will be created based on the current state of the release branches described in each repo's openedx catalog-info.yaml. In particular, for edx-platform, this will be a daily release. Make note of which release it was, people will want to know this.

...

Hey Open edX developers,
TL;DR: We are now in the pre-release phase for the next Open edX release: Palm. Code merged to master now will not be part of Palm. Keep this in mind as you make changes to master, especially needed fixes: They will need special attention, so reach out.
What is Palm? The next Open edX community release is named Palm. It will be based on the code as of today. We can include your future changes if you alert us to them.
What happened: Today we created the open-release/palm.master branches in our repos. As of now, changes you merge to master will contribute to the release after Palm, which will be called Quince.
What you should do: As you merge PRs to master, please be aware of fixes that might need to be applied to Palm. Let the Build-Test-Release Working Group know if there is a fix to be applied. They will need to be cherry-picked to ship as part of Palm, a.k.a. “backported”.
I know this gets confusing, but your code going onto master will now automatically be part of the Quince release (due next December). There is a new Quince wiki page for you to note things that will need to be considered when it comes time to release Quince. Please add features, caveats, and concerns to that page. If you are uncertain whether something should be mentioned there, add it. Or, talk to the Build-Test-Release WG and we'll figure it out.
What’s next? From now until the Palm release date, the Build-Test-Release group will be actively testing the release branch, finding bugs, triaging them, merging fixes to master, and backporting them to Palm. The Build-Test-Release Testing Coordinator will be kicking off this process soon, and they are happy to take volunteers to find and fix bugs. Keep an eye out if you’re interested. Even if you don’t actively participate, you can help this process by promptly reviewing any bugfix PRs that are made in your repositories.
Have questions? If you want to know more, we have an FAQ about the Open edX community releases. Please reach out if you have any questions.
--Ned, on behalf of the community Build/Test/Release working group.

...

This will require you to make a few PRs. Have them reviewed from someone else on the Bulid-Test-Release WG.

5a.

...

In openedx/edx-documentation, open a PR and tag someone on BTR for review:

On the open-release/zebrawood.master branch:
- Update the titles of three books. The titles should be changed from “<Versionless Title>“ to “<Versionless Title>: <Version> Release“.
- Also change intro paragraphs that explain what the book applies to.
- For example, https://github.com/edx/edx-documentation/pull/1867
- In each book, update source/index.rst and source/conf.py
  - "Building and Running an Open edX Course"
    - edx-documentation/en_us/open_edx_course_authors
  - "Installing, Configuring, and Running the Open edX Platform"
    - edx-documentation/en_us/install_operations
  - "Open edX Learner's Guide"
    - edx-documentation/en_us/open_edx_students
- In shared/conf.py, update the “release_line” variable to have the name of the release:
  Code Block
  release_line = "zebrawood"

5b. Ask Axim to activate hidden release versions of each book

File an Axim systems request to do the following:

Log into http://readthedocs.org as “openedx-rtd-maintainer”
Find the following Open edX book projects:
For each, find the new release version in the Versions tab, and make it Active. Keep it Hidden until the release is official.
- If the new release isn’t in the version list:
  - Check that the webhook is properly configured in GitHub openedx/edx-documentation.
  - Then create any branch in the repo to force readthedocs to synchronize the branches as versions.

5c. Add the latest release to the main docs site

In openedx/docs.openedx.org, open a PR and tag someone on BTR for review:

...

Create a new file at source/community/release_notes/palm.rst

Add a title to it like the following:
Code Block
Open edX Palm Release #####################

Update source/community/release_notes/index.rst, add a new line to the toctree so it looks something like this:

...

language	diff

...

Ask Axim to activate hidden release versions of each book

File an Axim systems request to do the following:

Log into http://readthedocs.org as “openedx-rtd-maintainer”
Find the following Open edX book projects:
- https://readthedocs.org/projects/docsopenedxorg/
- All books listed in the intersphinx_mapping in conf.py of docs.openedx.org
  - NOTE: All repos in the intersphinx_mapping need to have a book built for the current release in order for the overall docs.openedx.org book to build.
  - Because not all repos are explicitly tagged for release (and thus don’t have an open-release/release.master branch), the following procedure must be followed:
    - For each transitive dependency, figure out the version tag that is part of the current named release (for example for Sumac, we included XBlock v5.1.0 - determined by looking at the edx-platform base requirements, grabbing the package version, and converting it to the tag name)
    - When asking Axim to enable the book, they should enable a book off the tag but give it the slug open-release-TREE-master:
      Image Added
  - Note: the slug rename is a beta feature as of March 2025 and is only enabled on current (as of 18 Mar 2025) intersphinx books. See https://github.com/readthedocs/readthedocs.org/issues/12057 - file a support ticket if we need this feature enabled for more books.
For each, find the new release version in the Versions tab, and make it Active. Keep it Hidden until the release is official.
- If the new release or tag isn’t in the version list:
  - Then create the branch or tag in the repo to force readthedocs to synchronize the branches as versions.

5b. Add the latest release to the main docs site (This should already be in progress or done as part of the Release Docs process)

In openedx/docs.openedx.org, open a PR and tag someone on BTR for review:

Create a new directory at source/community/release_notes/ following the pattern for previous releases. Each directory should have 2 files, feature_release_notes.rst and dev_op_release_notes.rst, along with any other Product-specific release notes. If these files do not exist, copy the directory and files from the previous release, and remove all the text (just leaving the headings and toctree)
Update source/community/release_notes/index.rst, add a new line to the toctree so it looks something like this:

Code Block

language	diff

.. toctree::
    :maxdepth: 2

+    PalmSumac: The nextCurrent releaseRelease <palm><sumac>
     OliveTeak: TheJune current2025 releaseRelease <olive><teak>
     named_release_branches_and_tags
     old_releasesUlmo: December 2025 Release <ulmo>

.. toctree::
    :maxdepth: 1

    old_releases
    named_release_branches_and_tags

Update source/community/release_notes/named_release_branchs_and_tags.rst with a new section for the new release.
- For example: https://github.com/edx/edx-developer-docs/pull/30 (This was in the old repo before this file was moved to the openedx/docs.openedx.org repo but the delta should be very similar.) /pull/693/files
Once the PR has been created, contact the Release Documentation Expert so that they can review and merge the PR.

5d. Inform edx-platform developers via the PR template

...

5c. Make the new release notes the “latest” (major only)

In openedx/docs.openedx.org, make a PR (example) with the following changes, tagging someone on BTR for review:

Update source/conf.py to point the latest release to the latest release page.

Code Block

language	diff

rediraffe_redirects = {
-    "community/release_notes/latest.rst": "community/release_notes/yuca.rst",
+    "community/release_notes/latest.rst": "community/release_notes/zebrawood.rst",
}

6. Create the release Transifex project

...

Code Block

git clone https://github.com/openedx/openedx-translations.git
cd openedx-translations
mkvirtualenv openedx-translations
pip install -r requirements/requirements.txt
# Dry run the name fix
make TRANSIFEX_PROJECT_SLUG='openedx-translations-zebrawood' fix_transifex_resource_names_dry_run
# If runs without errors, run the actual command:
make TRANSIFEX_PROJECT_SLUG='openedx-translations-zebrawood' fix_transifex_resource_names

7 Gain LTI Certification for the release

Reach out to the LTI working group to certify this release for LTI. See the https://openedx.atlassian.net/wiki/spaces/~6193b016d5986c006a6460ab/pages/3452600321/How+to+run+the+LTI+Validation+Test?force_transition=403f9580-7954-421a-9b71-8da2cdf771e9 instructions.

🎁 Tagging a release or release candidate (Tagging Numbered Releases)

...

1. Prepare for the tagging a week before it is scheduled….

1a. Schedule a release ceremony

Schedule a meeting for the day of release, including:

...

Search for open pull requests against the release branch. For example, for Nutmeg, we would search: https://github.com/pulls?q=is%3Aopen+is%3Apr+base%3Aopen-release%2Fnutmeg.master+archived%3Afalse.

1d. Create a wiki pages for release process notes

Create a child of this page for your own notes: Open edX Release Manager Notes

...

Info
Don’t create a tag for testing, because once it is pulled by other developers or processes, it becomes very hard to delete - specially on a busy repository such as edx-platform.

Code Block
tag_release --doit --branch --skip-invalid --search-branch open-release/zebrawood.master --override-ref open-release/zebrawood.master you/test/z.1rc1.1

The .1 suffix is so that you can make a .2 if something needs to be fixed.

2c. Test the release one last time

At the discretion of the release manager, consider doing some more testing at this point.

Here’s a way you can do that:

Code Block
tutor config save --set OPENEDX_COMMON_VERSION=you/test/z.1 tutor local launch

Where <y> is the most recent tagged release.

2d. Create RC or release tags

Info
Execute this step if, and only if, there were no problems up to it. It is not practical to overwrite a tag on busy git repositories. If there are any errors, a new tag will have to be created.

For each tagged repo, make tags for the release or release candidate. The tag name is different for the two:

Release candidate: the tag should be open-release/$RELEASE.XrcY, where X is the number of the release, and Y is the number of the RC.
Release: the tag should be should be open-release/$RELEASE.X, where X is the number of the release.

Code Block
tag_release --doit --tag --skip-invalid --search-branch open-release/zebrawood.master --override-ref you/test/z.1rc1.1 open-release/zebrawood.1rc1 # for release candidate # or: as edx-platform.

Code Block
tag_release --doit --tagbranch --skip-invalid --search-branch open-release/zebrawood.master --override-ref you/test/z.1.1 open-release/zebrawood.1 # for release

You can delete the test branches you made once the release is marked:

Code Block
tag_release --doit --branch --skipoverride-invalidref --reverse you/test/z.1rc1.1

2e. Add the list of tagged repositories to the notes page

Just like this: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3604807768/Olive.1#Notes

This will give BTR an answer to the question “Which repositories were tagged?”, which will certainly be asked many times.

2f. You’ve made a release!

Congrats, you’ve tagged a new Open edX release!

Now, read through the follow-up steps below, and make sure they make sense. In the next ~day you’ll either need to do yourself them or delegate them to others.

3. Kick off the community-supported distribution release

Immediately inform the maintainer of community-supported distribution that the upstream release tags have been created and that the distribution release can proceed.

As of Palm, the community-supported distribution is Tutor. You can reach its maintainers by creating a thread on the forums and tagging @tutor-maintainers.

4. Update the documentation

This can happen concurrently with the Tutor Release step.

4a. Ask Axim to un-hide the release versions of each book (major only)

File an Axim systems request to do the following:

Log into http://readthedocs.org as “openedx-rtd-maintainer”
Find the following Open edX book projects:
Make the latest release un-hidden.
Keep the last three releases Active and not Hidden.
Make the releases older than that Active and Hidden.

4b. Make the new release notes the “latest” (major only)

In openedx/docs.openedx.org, make a PR (example) with the following changes, tagging someone on BTR for review:

Update source/conf.py to point the latest release to the latest release page.

Code Block

language	diff

rediraffe_redirects = {
-    "community/release_notes/latest.rst": "community/release_notes/yuca.rst",
+    "community/release_notes/latest.rst": "community/release_notes/zebrawood.rst",
}

Update source/community/release_notes/index.rst:
- Change “Zebrawood: The next release <zebrawood>” to “Zebrawood: The current release <zebrawood>”
- Remove “Yucca: The current release <yucca>”
Update source/community/release_notes/named_release_branches_and_tags.rst (example)
Add “yucca” to the list at source/community/release_notes/old_releases.rst
In source/index.rst change “Current Release: Yucca <community/release_notes/yucca>” to “Current Release: Yucca <community/release_notes/yucca>”

...

open-release/zebrawood.master you/test/z.1rc1.1

The .1 suffix is so that you can make a .2 if something needs to be fixed.

2c. Test the release one last time

At the discretion of the release manager, consider doing some more testing at this point.

Here’s a way you can do that:

Code Block
tutor config save --set OPENEDX_COMMON_VERSION=you/test/z.1 tutor local launch

Where <y> is the most recent tagged release.

2d. Create RC or release tags

Info
Execute this step if, and only if, there were no problems up to it. It is not practical to overwrite a tag on busy git repositories. If there are any errors, a new tag will have to be created.

For each tagged repo, make tags for the release or release candidate. The tag name is different for the two:

Release candidate: the tag should be open-release/$RELEASE.XrcY, where X is the number of the release, and Y is the number of the RC.
Release: the tag should be should be open-release/$RELEASE.X, where X is the number of the release.

Code Block

tag_release --doit --tag --skip-invalid --search-branch open-release/zebrawood.master --override-ref you/test/z.1rc1.1 open-release/zebrawood.1rc1		# for release candidate
# or:
tag_release --doit --tag --skip-invalid --search-branch open-release/zebrawood.master --override-ref you/test/z.1.1 open-release/zebrawood.1				# for release

You can delete the test branches you made once the release is marked:

Code Block
tag_release --doit --branch --skip-invalid --reverse you/test/z.1rc1.1

2e. Add the list of tagged repositories to the notes page

Just like this: Olive.1

This will give BTR an answer to the question “Which repositories were tagged?”, which will certainly be asked many times.

2f. You’ve made a release!

Congrats, you’ve tagged a new Open edX release!

Now, read through the follow-up steps below, and make sure they make sense. In the next ~day you’ll either need to do yourself them or delegate them to others.

3. Kick off the community-supported distribution release

Immediately inform the maintainer of community-supported distribution that the upstream release tags have been created and that the distribution release can proceed.

As of Palm, the community-supported distribution is Tutor. You can reach its maintainers by creating a thread on the forums and tagging @tutor-maintainers.

4. Update the documentation

This can happen concurrently with the Tutor Release step.

See https://openedx.atlassian.net/wiki/spaces/COMM/pages/19662426/Process+to+Create+an+Open+edX+Release#5.-Update-the-documentation for steps to publish the docs. The following should be completed by BTR:

4a. Update the release planning wiki pages (major only)

Consider “Yucca” to be the release you are cutting no"w, and “Zebrawood” to be the next release after that (six months from now).

...

Finally, update Open edX Release Schedule .

...

4b. Inform edx-platform developers via the PR template (major only)

Update the Confluence page linked from a pull request template in the master branch of edx/edx-platform to encourage developers to contribute bugfixes back to the latest release branch. Drop any mention of the previous release, which is now unsupported. See

Update the pull request template in the master branch of edx/edx-platform to encourage developers to contribute bugfixes back to both the upcoming & next release branches (see for instance this PR).

5. Announce to the community

...

Version	Old Version 246	New Version Current
Changes made by	Kyle McCormick	Sarina Canelake
Saved on	Oct 17, 2024	Jun 26, 2025

Versions Compared

Key

Tags and Branches

1. Prepare for the cut a week before it is scheduled….

1a.

1b. Schedule a release ceremony

Schedule a release ceremony

1b. Pre-announce the master branches

1c. Create a wiki pages for release process notes

5a.

5b. Ask Axim to activate hidden release versions of each book

5c. Add the latest release to the main docs site

Ask Axim to activate hidden release versions of each book

5b. Add the latest release to the main docs site (This should already be in progress or done as part of the Release Docs process)

5d. Inform edx-platform developers via the PR template

5c. Make the new release notes the “latest” (major only)

6. Create the release Transifex project

7 Gain LTI Certification for the release

🎁 Tagging a release or release candidate (Tagging Numbered Releases)

1. Prepare for the tagging a week before it is scheduled….

1a. Schedule a release ceremony

1d. Create a wiki pages for release process notes

2c. Test the release one last time

2d. Create RC or release tags

2e. Add the list of tagged repositories to the notes page

2f. You’ve made a release!

3. Kick off the community-supported distribution release

4. Update the documentation

4a. Ask Axim to un-hide the release versions of each book (major only)

4b. Make the new release notes the “latest” (major only)

2c. Test the release one last time

2d. Create RC or release tags

2e. Add the list of tagged repositories to the notes page

2f. You’ve made a release!

3. Kick off the community-supported distribution release

4. Update the documentation

4a. Update the release planning wiki pages (major only)

4b. Inform edx-platform developers via the PR template (major only)

5. Announce to the community

Content Comparison

Versions Compared

Key

Tags and Branches

1. Prepare for the cut a week before it is scheduled….

1a.

1b. Schedule a release ceremony

Schedule a release ceremony

1b. Pre-announce the master branches

1c. Create a wiki pages for release process notes

5a.

5b. Ask Axim to activate hidden release versions of each book

5c. Add the latest release to the main docs site

Ask Axim to activate hidden release versions of each book

5b. Add the latest release to the main docs site (This should already be in progress or done as part of the Release Docs process)

5d. Inform edx-platform developers via the PR template

5c. Make the new release notes the “latest” (major only)

6. Create the release Transifex project

7 Gain LTI Certification for the release

🎁 Tagging a release or release candidate (Tagging Numbered Releases)

1. Prepare for the tagging a week before it is scheduled….

1a. Schedule a release ceremony

1d. Create a wiki pages for release process notes

2c. Test the release one last time

2d. Create RC or release tags

2e. Add the list of tagged repositories to the notes page

2f. You’ve made a release!

3. Kick off the community-supported distribution release

4. Update the documentation

4a. Ask Axim to un-hide the release versions of each book (major only)

4b. Make the new release notes the “latest” (major only)

2c. Test the release one last time

2d. Create RC or release tags

2e. Add the list of tagged repositories to the notes page

2f. You’ve made a release!

3. Kick off the community-supported distribution release

4. Update the documentation

4a. Update the release planning wiki pages (major only)

4b. Inform edx-platform developers via the PR template (major only)

5. Announce to the community