Table of Contents |
---|
In this document, I'll use "zebrawood" for the release you are making, and "yucca" for the previous release.
Overview
Repos
An Open edX release is comprised of specific versions of many repos. The participating repos are determined by examining the OEP-2 openedx.yaml files in each repo.
Tags and Branches
...
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
This page could use several updates, including:
|
Contents
Table of Contents |
---|
🏙️ Overview
This document explains how to make an Open edX release. In this document, I'll use "zebrawood" for the release you are making, and "yucca" for the previous release.
Schedule
The schedule of cuts and releases is maintained here: Open edX Release Processes
Repos
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 OEP-2 openedx.yaml files in each repo. In other words, every repository that has an openedx.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-release: {ref: master} |
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 ".
Docs
Documentation has a process for producing release-specific versions of some books. For information about preparing documentation for an Open edX release, see Open edX Release Documentation and Versioning.
Create the release branches
The repo-tools repo has a script, tag_release.py, to branch and tag the proper repos. The repos are indicated by an "openedx-release" entry in their openedx.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.
Code Block |
---|
$ tag_release --doit --branch open-release/zebrawood.master
edx/configuration: master (branch) d213681
2016-02-17 Fred Smith: Merge pull request #2784 from edx/add-support-url
edx/edx-analytics-data-api-client: 0.6.1 (tag) d621288
2015-05-07 Dennis Jen: Merge pull request #20 from edx/dsjen/update-setup
edx/edx-certificates: master (branch) a2ed4ed
2015-08-28 Kelketek: Merge pull request #49 from edx/make_tmp_dir
edx/edx-platform: release (branch) 71b3080
2016-02-17 Nimisha Asthagiri: Merge pull request #11532 from edx/rc/2016-02-16
.. and other repo information ..
Is this correct? [y/N] y
Success! |
The tag_release.py script has other options to control it in various ways.
The branch will be created based on the current state of the release branches described in each repo's openedx.yaml. In particular, for edx-platform, this will be a weekly release. Make note of which release it was, people will want to know this.
NOTE: the tag_release.py script is still fairly new. Double-check what it did to see how it looks.
Get release notes started
Tell your doc writer the date the release was based on. Also find the date the previous release was based on. They will use these two dates to comb the edx.org release notes for information to go into the Open edX release notes.
Announce the creation of the Open edX release branch
Send an email to eng-all@edx.org explaining that the open-release branch has been cut from an edx.org release.
Announce upcoming release to the community
An email to the edx-code mailing list will do. Here's how David Baumgold (Deactivated) announced the upcoming Birch release: https://groups.google.com/d/msg/edx-code/lsk5uJLWpWA/6rPS7T8HYooJ
You can also alert the doc team to include an announcement in the "Coming Soon" section of the weekly release notes.
Also send out an email to eng-all@edx.org to let everyone at edX know about the upcoming Open edX release, as well. This should remind people to update the wiki page for the release (for example this page for the Eucalyptus release). They should keep track of bugfixes that are in flight, so that when they get merged into master, they can also be pulled into the release candidate branch.
Make release-specific changes on the release branch
Some changes need to be made directly on the release branch, because they are intended for the release itself, and should not be on master.
Translations
We upload release-specific versions of the translated strings to Transifex. This is done by editing the .tx/config file on the release branch. Add two clauses like this:
Code Block |
---|
[open-edx-releases.release-zebrawood]
file_filter = conf/locale/<lang>/LC_MESSAGES/django.po
source_file = conf/locale/en/LC_MESSAGES/django.po
source_lang = en
type = PO
[open-edx-releases.release-zebrawood-js]
file_filter = conf/locale/<lang>/LC_MESSAGES/djangojs.po
source_file = conf/locale/en/LC_MESSAGES/djangojs.po
source_lang = en
type = PO |
Make sure that the file has no other "release-" resources.
Help Links
The documentation process page (Open edX Release Documentation and Versioning) has things to do, including updating the help links in edx-platform. Be sure to do this before release day, so that changes have time to pass edx-platform CI gates.
Make a release or release candidate
Releases and release candidates are tags marking specific versions of all the repos, packaged as a box file. Take care with the steps to create and tag these. It's surprising, but you have to edit files to refer to the tags before you can create the tag.
Choose box names
You will be making Vagrant box files. The names of the box files are important. The file name will include the name of the release, and the date, but does not include "rc1" or any other version tag. Boxes can be used for multiple versions of a release. Putting the version in the name would just confuse people. Name the box like this: $RELEASE-$TYPE-$DATE.box, for example:
zebrawood-devstack-2016-02-17.box
In the unlikely event of having to make and release a second box in the same day, add a "-2" suffix: zebrawood-devstack-2016-02-21-2.box
Update Vagrantfile
Even if you will not be making a new box file for this version, you need to update the Vagrant files. The release Vagrant files (vagrant/release/devstack/Vagrantfile and vagrant/release/fullstack/Vagrantfile) will need to be updated to pull down the correct box file when the appropriate value is set for the OPENEDX_RELEASE
environment variable. Pay close attention to the syntax in the file; the name you put there doesn't have the .box suffix:
Code Block |
---|
openedx_releases = {
"open-release/zebrawood.master" => "zebrawood-devstack-2016-02-17",
"open-release/zebrawood.1rc1" => "zebrawood-devstack-2016-02-17",
}
|
Release candidates have a generic clause ".master" (for testing with the branch name), and a specific clause ".1rc1" for actual use with the tag.
Also update the default, if this is a final (not rc) release:
Code Block |
---|
openedx_releases.default = "zebrawood-fullstack-2016-02-17" |
Make these changes on the release branch and on master of configuration.
Make a test tag
Because real releases are made from tags, and very occasionally the difference between tags and branches is important, all builds should be done from tags. To make the vagrant boxes from a tag, but not yet mark the release, we'll make a test tag. The tag should use your personal prefix ("you/"), and be named for the release you are working on, but with an additional .n suffix:
Code Block |
---|
tag_release --doit --tag --skip-invalid --override-ref open-release/zebrawood.master you/test/zebrawood.1rc1.1 |
The .1 suffix is so that you can make a .2 if something needs to be fixed.
Make Vagrant boxes
You do not need to make new devstack boxes for every release candidate, or for the final release, but you do need to make new fullstack boxes for every release. A vagrant box is a pre-made snapshot that can speed the installation process. The first release candidate of every Open edX release should have a new devstack box, but subsequent candidates, and the final version, can probably do without.
Clone the configuration repo and build Vagrant boxes from scratch for fullstack and possibly devstack. Make sure to use the "base" version, not the "release" version.
Code Block | ||
---|---|---|
| ||
git clone https://github.com/edx/configuration.git
cd configuration
export OPENEDX_RELEASE=you/test/zebrawood.1rc1.1
git checkout $OPENEDX_RELEASE
python -m virtualenv venv
. venv/bin/activate
make requirements
cd vagrant/base/fullstack # or devstack
vagrant up |
If you run into issues with the process of building Vagrant boxes from scratch, work with devops.
To reduce the size of the box file, ssh into the box and execute this command:
Code Block |
---|
sudo /edx/app/edx_ansible/pre-box # takes about 4 minutes |
Once the box is up and running, export it to a box file. (You need to run the commands on the host computer, not on the Vagrant virtual machine.)
Code Block | ||
---|---|---|
| ||
vagrant package # can take 8 to 12 minutes |
This will create a package.box
file.
Upload Vagrant boxes
Upload the file to Amazon S3 with the right box name. Be sure to use the name you put into the Vagrantfile. How you do this depends on whether you have credentials to upload files to Amazon S3, or you don't:
If you have Amazon S3 credentials:
Code Block aws --profile=edx s3 cp package.box s3://edx-static/vagrant-images/zebrwood-devstack-2016-02-17.box --acl public-read aws --profile=edx s3 cp package.box s3://edx-static/vagrant-images/zebrawood-fullstack-2016-02-17.box --acl public-read
- If you don't have Amazon S3 credentials:
- Upload the file to Google Drive
- Tell Devops, they will move it to Amazon S3.
Update box directory
Update the wiki page that lists the boxes: Open edX Releases.
- Add the new box, and a new row in the table if need be. Be careful when editing URLs that you change both the text and the link.
- Add the SHA1 hash of the box file, from "shasum package.box"
- Click the torrent URLs to make sure they work. If they 404, then the file doesn't exist, or has the wrong permissions. If you get "The s3.amazonaws.com page isn’t working. s3.amazonaws.com didn’t send any data," then click it again until it gives you a file of about 220Kb. Amazon takes a while to get the torrent file going.
Test upgrade to master (??)
Create a devstack VM and a fullstack VM from the previous Open edX release:
Code Block |
---|
$ export OPENEDX_RELEASE="open-release/yucca.latest" # or whatever the previous release was.
$ vagrant up
... lots of output ...
# You don't need to make a snapshot, but it's really handy
$ VBoxManage list vms
"yucca_full_default_1451410759822_16267" {e7764d74-6f2f-49d2-8fab-4e8715272338}
"yucca_default_1452008513561_29129" {6e796982-7ed3-4dc3-9243-aacc0f47db29}
$ VBoxManage snapshot "yucca_default_1452008513561_29129" take pristine
# Later you can reset to this point with: $ VBoxManage snapshot "yucca_default_1452008513561_29129" restore pristine |
NOTE: Not sure this is good advice: For each one, try upgrading edx-platform to the "master" commit on edx-platform:
Code Block | ||
---|---|---|
| ||
cd /edx/app/edx_ansible/edx_ansible
sudo git checkout master
sudo git pull
cd playbooks/edx-east/
/edx/app/edx_ansible/venvs/edx_ansible/bin/ansible-playbook -i localhost, -c local edxapp.yml -e "@/edx/app/edx_ansible/server-vars.yml" |
If it fails, work with devops to figure out what's going wrong and how to fix it. Note that the above ansible command seems to only work for fullstack, since devstack doesn't have a /edx/app/edx_ansible/server-vars.yml
file. Still trying to figure out how to test this with devstack.
Test/Update the upgrade.sh script
The upgrade script is in the configuration repo at utils/vagrant/upgrade.sh. Make a branch from open-release/zebrawood/master for bringing upgrade.sh up to date, let's call it you/open-upgrade. Check on all the things from the Open edX release page for collecting devops details about this release, for example: Eucalyptus. Each of them should be accounted for in the upgrade.sh script or the playbooks it invokes.
For your devstack and fullstack boxes:
- Revert to the pristine snapshot.
- Bring up the box and ssh into it.
Download the upgrade.sh script and run it:
Code Block export CONFIGURATION_TARGET=you/open-upgrade curl -OL https://raw.github.com/edx/configuration/$CONFIGURATION_TARGET/util/vagrant/upgrade.sh bash upgrade.sh -c devstack -t open-release/zebrawood.master # Change devstack to fullstack when testing fullstack.
- This should upgrade the box from Yucca to Zebrawood. If it doesn't, fix the problem, push to the upgrade working branch, and try again.
- Once it works, merge the you/open-upgrade branch to open-release/zebrawood.master
Test clean installation
Test the native installation
Native Open edX Ubuntu 16.04 64 bit Installation
Create RC or release tags
For each tagged repo, make tags for the release or release candidate. The tag name is different for the two:
...
Code Block |
---|
tag_release --doit --tag --skip-invalid --override-ref you/test/zebrawood.1rc1.1 open-release/zebrawood.1rc1 # for release candidate
# or:
tag_release --doit --tag --skip-invalid --override-ref you/test/zebrawood.1.1 open-release/zebrawood.1 # for release |
It's tempting to do this before creating the Vagrant box. In practice, the first time you create the Vagrant box, it will probably fail, and you'll need to make some fixes. Therefore, it's better to wait until everything works properly before you make the tag.
Announce to the community
For Birch, we did both an email to edx-code and a post to the engineering blog. You should also let everyone at edX know that the Open edX release candidate branch has been cut, and they should notify you of all bugfixes merged to master for the next few weeks.
You should also create a Confluence page summarizing the status of the release candidate branch. Here's the one we used for Birch.
Collect bugfixes, create new release candidates
Over the next two weeks or so, keep an eye out for bugfixes going into master, so that important bugfixes also go into the release master branch. If there are a significant number of changes (however you want to define "significant"), you should create another release candidate. That consists of updating the Confluence page for the release candidate branch, tagging the repos, possibly creating and uploading new Vagrant boxes, testing the upgrades, and sending out another email to the community informing them of the new release candidate. If there's less than a week before the planned release date, and you're putting out a new release candidate, you should push back the planned release date so that everyone has more time to test on the new release candidate. (Be sure to announce to the community and to everyone at edX that the planned release date is being pushed back.)
The final version
(TODO: what has to happen differently for the final version?)
Run the translation commands to upload the latest text to Transifex:
Code Block |
---|
$ paver i18n_release_push |
Point releases
(TODO: how are they named, what has to be done differently to create them?)
Run the translation commands to upload the latest text to Transifex:
...
0".
tag_release.py
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 openedx.yaml
files. If a given repository is indeed eligible, the script will execute the requested branching or tagging operation on it.
Release Manager Permissions
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.
If so:
Before cutting or tagging any release:
Confirm that the release manager is, in fact, a member of the community-release-manager GitHub team. If not, have someone from Axim add them.
Confirm that the community-release-manager GitHub team grants write access to all the repos in the release and only the repos in the release.
If not:
Before cutting or tagging any release:
Invite an Axim team member to the release ceremony. They will need to add the release manager to community-release-manager add the beginning of the ceremony and remove them from it add the end.
✂️ Cutting a release (Making the Master Branches)
1. Prepare for the cut a week before it is scheduled….
1a. Look into “maybe” repos
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:
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!
1c. 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.
1d. Create a wiki pages for release process notes
Create a child of this page for your own notes: Open edX Release Manager Notes
Example: Palm.master
2. Hold a release cutting ceremony
Get together on a video call. Release manager: share your screen so everyone can follow along. If everyone’s comfortable with it, record it for future reference.
2a. Freeze edx-sandbox for the release
Starting with Quince, we need to freeze the Python dependency pins for the edx-platform codejail sandbox environment (also known as “edx-sandbox”). This allows operators to smoothly upgrade their instructor-authored code from release to release. The file needs to exist both in the release and on master, so this step needs to be done before the release cut.
To do this:
copy
./requirements/edx-sandbox/base.txt
to a new file named./requirements/edx-sandbox/releases/<RELEASE.txt>
git-add the new file and open a pull request against edx-platform master
tag someone for review and merge it before cutting the release.
That’s it! Here’s an example: https://github.com/openedx/edx-platform/commit/8eb9ee7b5c758351fe197a203f82c1141e127f61 .
2b. Testing before creating release branches
If you want to try a dry-run of the release before making any release branches, make a branch under your personal name. Don't use the full release name in the branch name, or people will think it's a release. Follow the instructions for "Create the release branches", but use "yourname/test-z.1" instead of "open-release/zebrawood.master", for example:
Code Block |
---|
$ tag_release --doit --skip-repo "*-internal" --branch yourname/test-z.1 |
2c. Create the release branches
The repo-tools repo has a script, tag_release.py, to branch and tag the proper repos. The repos are indicated by an "openedx-release" entry in their openedx.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.
Code Block |
---|
$ tag_release --doit --skip-repo "*-internal" --branch open-release/zebrawood.master
edx/configuration: master (branch) d213681
2016-02-17 Fred Smith: Merge pull request #2784 from edx/add-support-url
edx/edx-analytics-data-api-client: 0.6.1 (tag) d621288
2015-05-07 Dennis Jen: Merge pull request #20 from edx/dsjen/update-setup
edx/edx-certificates: master (branch) a2ed4ed
2015-08-28 Kelketek: Merge pull request #49 from edx/make_tmp_dir
edx/edx-platform: release (branch) 71b3080
2016-02-17 Nimisha Asthagiri: Merge pull request #11532 from edx/rc/2016-02-16
.. and other repo information ..
Is this correct? [y/N] y
Success! |
The tag_release.py script has other options to control it in various ways.
The branch will be created based on the current state of the release branches described in each repo's openedx.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.
Double-check what the script did to see that it looks correct.
3. Make announcements rights after the release is cut
3a. Get release notes started
Tell your doc writer the date the release was based on. Also find the date the previous release was based on. They will use these two dates to comb the edx.org release notes for information to go into the Open edX release notes.
3b. Get the blog post started
??? Reach out to
3c. Update the release planning wiki pages
Consider “Yucca” to be the release you are cutting now, and “Zebrawood” to be the next release after that (six months from now).
Under Open edX Release Planning …
Create a new planning page for the next release:
Name it Next Release: Zebrawood.
You can use Next Release: Yucca page as a template for the structure of the page.
Indicate that current planning page, Next Release: Yucca, is no longer active:
Rename it Upcoming Release: Yucca.
Add a warning that new changes should be added to Next Release: Zebrawood.
Finally, update Open edX Release Schedule .
3d. Announce the creation of the Open edX release branch
For a 2U person to do: Send an email to edx-tech-announce@2u.com explaining that the open-release branch has been created from an edx.org release. Here's an example:
Hey everyone,
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, 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, your day-to-day work is contributing to the release after Palm, which will be called Quince. The community will be stabilizing and testing Palm, and we'll be making fixes on the Palm branches, leading up to the official Palm release in early June.
What you should do: As you do your work, please be aware of fixes that might need to be applied to Palm. I can help get the fix into the release, but you need to let us know there is a fix to be applied. They will need to be cherry-picked to ship as part of Palm.
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 me and we'll figure it out.
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.
Thanks for all your hard work! You make Open edX software the valued open source platform it is!
--Ned, on behalf of the community Build/Test/Release working group.
3e. Announce upcoming release to the community
Create a topic in the Announcements - Releases category on discuss.openedx.org. ((Add some boilerplate here))
If you created a pre-release branch, you should probably not write a post in “Releases” but in the build/test/release working group category. (see for instance this announcement)
Please notify the DEPR working group in the #wg-depr-slash-n-burn channel in the Open edX Slack, so that the DEPR working group can help write release notes of deprecated code in accordance with the DEPR Release Notes Process .
3f. Get the test process started
Reach out to the Build-Test-Release Testing Manager to make sure they’re kicking off the testing process for the newly cut release.
When they have a test plan ready, add it to Open edX Release Testing.
3g. Get the community-supported distribution release process started
Immediately inform the maintainers 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. Make release-specific changes on the release branch
Some changes need to be made directly on the release branch, because they are intended for the release itself, and should not be on master.
Release line
In edx-platform/openedx/core/release.py, edit the RELEASE_LINE line to indicate the release:
Code Block |
---|
RELEASE_LINE = "zebrawood" |
5. Update the documentation
This will require you to make a few PRs. Have them reviewed from someone else on the Bulid-Test-Release WG.
5a. Changes guide book titles for the release
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:
“Open edX Building and Running a Course”
https://readthedocs.org/projects/open-edx-building-and-running-a-course/”edX Installing, Configuring, and Running”
https://readthedocs.org/projects/edx-installing-configuring-and-running/”Open edX Learner's Guide”
https://readthedocs.org/projects/open-edx-learner-guide/
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 thetoctree
so it looks something like this:Code Block language diff .. toctree:: :maxdepth: 2 + Palm: The next release <palm> Olive: The current release <olive> named_release_branches_and_tags old_releases
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
docs.openedx.org
repo but the delta should be very similar.)
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
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).
6. Create the release Transifex project
Note |
---|
Translations after OEP-58 requires a new Transifex project for each named release. This will ensure the translations sources and code source stay in sync after Creating multiple projects isn’t ideal and can be revisited if it turns out to harm the Translator Experience. |
6a Double check the openedx-translations repository branch
Go to the https://github.com/openedx/openedx-translations repository and ensure it has the proper release branch e.g. open.release/zebrawood.master
.
6b Clone the openedx-translations Transifex project
Create a new Transifex project:
openedx-translations-zebrawood
.Add all the languages from the
openex-translatiosn
Transifex project.
6c Configure the GitHub Transifex App
This is a manual step:
Go to the Zebrawood Transifex project (
openedx-translations-zebrawood
) configuration settingsIn the Integrations tab, click on the GitHub App integration “Install” button
Allow the integration
Grant permission to your account
Grant permission to the
openedx/openedx-translations
repository
Continue the wizard to configure the project integrations to the following:
Select repo step:
Selected repository:
openedx/openedx-translations
Selected branch: Set it to the release branch e.g.
open.release/zebrawood.master
Select files step:
Set the path to your YAML configuration file to
transifex.yml
Sync content step:
PULL CONTENT:
Fetch content automatically
PUSH CONTENT:
100% reviewed
Set “How would you like Transifex to push translations to GitHub?” to
Create a Pull Request
andNo grouping
Add a prefix to the commit message:
chore:
Click on the Update Settings button
Wait for the sync to complete. It takes about an hour.
☑️ Ensure that all the resources has been added.
6d Update the Transifex resources names and tags
The GitHub Transifex App integeration puts an inconvenient names for resources like "translations..frontend-app-something..src-i18n-transifex-input--main"
instead of "frontend-app-something"
.
This can be fixed with the following command locally:
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 |
🎁 Tagging a release or release candidate (Tagging Numbered Releases)
Releases are tags marking specific versions of all the repos. Take care with the steps to create and tag these. It's surprising, but you have to edit files to refer to the tags before you can create the tag.
There are two types of tagged releases:
the major release (zebrawood.1) and
the minor (“point”) releases (zebrawood.2, zebrawood.3, and sometimes zebrawood.4+).
The steps below apply to both major & minor releases, unless they say (major only).
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:
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!
Ask someone from Axim to put it on the community working groups calendar.
1b. Double-check that the test plan is complete (major only)
Go to the Test Plan spreadsheet and check whether testing has been sufficiently completed (to the discretion of the release manager).
1c. Double-check that all known issues have been addressed
Prior to making a release (major, minor, or even a candidate), it is imperative that all known issues be fixed. You can check at the GitHub Project board with an appropriate filter such as “label:bug milestone:lilac.1”. Over time other labels or milestones may be incorporated, but just keep in mind that issues such as an uninstallable tag are unacceptable.
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
Example: Olive.1
2. Hold a release tagging ceremony
2a. Make a test branch (not a tag!)
To test the installation, but not yet mark the release, we'll make a test branch. The branch should use your personal prefix ("you/"), and be named for the release you are working on, but with an additional .n suffix. Don't use the full release name, or people will find the branch and think it is a release:
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:
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: 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:
“Open edX Building and Running a Course”
https://readthedocs.org/projects/open-edx-building-and-running-a-course/”edX Installing, Configuring, and Running”
https://readthedocs.org/projects/edx-installing-configuring-and-running/”Open edX Learner's Guide”
https://readthedocs.org/projects/open-edx-learner-guide/
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 thelatest
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>”
4c. 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).
Under Open edX Release Planning …
Rename Upcoming Release: Yucca to simply Yucca
Move Yucca under Older Release Planning Pages .
(Note: There should still be a Next Release: Zebrawood page underneath Open edX Release Planning )
Finally, update Open edX Release Schedule .
4d. Inform edx-platform developers via the PR template (major only)
Update the 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 for instance this PR.
5. Announce to the community
Create a topic in the Announcements - Releases category on discuss.openedx.org.
Change the topic line in the #ops
channel in Slack.
5a. Announce the new named release (major only)
Make sure a blog post gets published.
Update the Support Windows chart. For example: https://github.com/openedx/repo-tools/pull/325/files. Be sure to read the top of barcalendar.py to understand how to update the chart.
Have the 2U contact announce the release within 2U. Send an email to edx-tech-announce@2u.com, for example:
The Olive release of the Open edX platform was officially released on Monday 12/12! Thanks for everything you did to help make it happen.
This is not the end of Olive: the open-release/olive.master branches are still accepting fixes. When fixing problems in your normal course of work, please consider whether it makes sense to backport it to Olive.
I know the release process can be a bit mysterious:
- The open-release/olive.master branches were created in 44 repos on October 11th.
- Since then, all work on master or main branches has only been part of Olive if it was explicitly cherry-picked or backported.
- The master or main work since October 11th has been the start of the Palm release that will happen next June.
If you have questions, we have an FAQ wiki page about Open edX releases, and you can always reach out to us in the #interest-openedx 2U Slack channel.
Thanks again for helping make the Open edX platform available around the world to the thousands of sites using it for their online education!
--Ned.
6. Keep an eye out for bugfixes that should be backported
Over the next two weeks or so, keep an eye out for bugfixes going into master, so that important bugfixes also go into the release master branch. These will become part of the following minor release.
Generally, zebrawood.3 is the final minor release, but in cases where we have important follow-up fixes, you can tag zebrawood.4, etc.
7. (For the final release) Check that release changes made it to master
Note |
---|
I’m not sure that this step makes sense still -Kyle |
During the stabilization of the release, you may have changes made directly on the open-release/zebrawood.master branch. Take a look at what's there, and compare to master to be sure all the changes end up on master also. Keep in mind that there are a few changes on the release branch that should only be on the release branch (RELEASE_LINE for example).
Code Block |
---|
# gittreeif is a handy function from https://github.com/nedbat/dot/blob/master/.bashrc
GIT_PAGER=cat gittreeif origin/open-release/hawthorn.master log origin/open-release/zebrawood.master ^origin/master |