Versions Compared

Old Version 233

changes.mady.by.user Maksim Sokolskiy

Saved on

compared with

New Version Current

changes.mady.by.user Omar Al-Ithawi

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

...

Currently the job that makes the PRs is running on Jenkins infrastructure at 2U. If a 2U engineer is available to run these jobs manually, you can ask them to do that now and merge the latest translations PRs before you cut the release branches.

...

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/pull/31039 )
- If the PRs are not merged at the time (this is expected hence the above note), leave a note about them so that we can backport the commit at a later time.
Why we need to this: The point of doing this is that we ensure the shortest lag possible between the last time a translator review/translate string and the branch cut date. i.e. If the syncing happens on a weekly basis and we do the branch cut just a day before the scheduled weekly sync , then we would in theory lose 6 days of translation work.

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: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 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-clientopen-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!

...

3g. Get the community-supported distribution release process started

Immediately inform the maintainer 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 and its maintainer is Régis Behmo . 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.

...

We upload release-specific versions of the translated strings to Transifex. This is done by editing the edx-platform/.tx/config file on the release branch. Add two clauses like this:

Code Block
[o:open-edx:p:open-edx-releases:r: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

[o:open-edx:p:open-edx-releases:r: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.

⚠ The exact syntax of this file is undetermined as of 2022-06-09. Please see this PR for more information.

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:

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:

Code Block
languagediff
 .. 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.

...

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:

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:

    Code Block
    languagediff
     .. 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.

  • Once the PR has been created, contact the Release Documentation Expert so that they can review and merge the PR.

...

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

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

2b. Update and upload translations on the test branch

Note

This step is out of date. The release manager hasn’t done this since Nutmeg or earlier. Instead:

  • For major releases: Reach out to #wg-translations and inform them that the <zebrawood>.1 has been tagged. Hopefully, someone will know what that means and help you out.

  • For major & minor releases:Régis B. has some particular steps he does with openedx-i18n as part of the Tutor release process.

This should all be replaced when OEP-58 is implemented.

For this method, you should be using tutor and should have openedx/edx-platform on the target release branch locally.

2b1. Tutor

In the case that this is a new release, it is best to use Tutor’s Nightly branch, otherwise the Master branch is recommended. Using tutor, open a shell in cms while mounting the local edx-platform repo set to the target release branch.

Code Block
tutor dev run cms bash -m path-to-edx-platform

2b2. Setup

There are some setup items that are necessary as of nutmeg [last updated 2022-09-01]:

  1. Install the development requirements

  2. Uninstall the old transifex-client (v2)

  3. Install the new transifex-client (v3)

Code Block
make dev-requirements
curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

2b3. Transifex Credentials

Add your transifex credentials to ~/.transifexrc. Replace {TOKEN} with a token from Transifex.

Code Block
[https://www.transifex.com]
api_hostname = https://api.transifex.com
hostname = https://www.transifex.com
password = {TOKEN}
rest_hostname = https://rest.api.transifex.com
token = {TOKEN}
username = api

2b4. Generate, Compile, and Upload to Transifex

Open a new bash shell within the current shell and follow these commands to generate, compile and upload Translation files. Replace {release-version} in line 5 with the name of the release. It should match the files in .tx/config.

Code Block
bash
i18n_tool extract
i18n_tool dummy
i18n_tool generate
paver i18n_compilejs
tx push -s -r open-edx-releases.release-{release-version} open-edx-releases.release-{release-version}-js

2b5. Manually Renaming the Translations Files

In the case that this is the first time the resources are being uploaded to Transifex, log in to Transifex, find the files named django.po and djangojs.po, confirm that the slugs (check out the url) match the release version and rename the files to match the naming convention.

...

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 main branches continue to evolve after cutting the release.

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 settings

  • In 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 and No 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

...

Code Block
tutor config save --set OPENEDX_COMMON_VERSION=you/test/z.1
tutor images build --build-arg
OPENEDX_I18N_VERSION=open-release/<y> openedx
tutor local launch

Where <y> is the most recent tagged release.

...

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

4. Update the documentation

...

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 and translation naming, 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