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

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".

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.

$ 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:

[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.

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:

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:

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:

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.

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:

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.)

vagrant package							# can take 8 to 12 minutes

This will create a package.box file.

Upload Vagrant boxes

Rename the file with the name of the release, and the date, but do not use "rc1" or any other version tag. Boxes can be used for multiple versions of a release. Putting the version in the name just confuses 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

Either you have credentials to upload files to Amazon S3, or you don't.

If you have Amazon S3 credentials:

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.
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:

$ 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:

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:

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

Release Test Process

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:

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.

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:

$ paver i18n_release_push

Point releases

(TODO: how are they named, what has to be done differently to create them?)