You want to propose a change for a named Open edX release.

There are few different scenarios here, and few different moving parts. Once you get the hang of it, though, this should feel like a quick & easy process.

Making a change that also belongs on master (a “backport”)

Most changes to named releases should also be represented on the master branches. When a change is needed in a named release, the standard process it to make the change to master first, and then port the change back to the named release (hence the term backport). If you are unsure as to whether a backport is appropriate (e.g. it is unclear whether the change is a bugfix or a new feature), seek guidance from the relevant product owner by posting in the #wg-product-core Slack channel.

When opening a PR to a named release branch, tag the Release Manager from the Build-Test-Release Working Group for a review. You can find the release manager in the working group’s README. Although not required, getting a first PR review from one of your team members will show the Release Manager that someone else’s eyes have already been on your PR, which makes their job easier.

The exact mechanics of backporting depend on whether you’re merging to a:

• top-level repository, signified by the presence of a open-release/XXX.master named release branch; or a

• library repository, which is installed into the release by pip or npm and thus doesn’t have a named release branch.

Backporting to a top-level repository

1. Ensure the change is already merged to master and deployed.

2. Find the commit hash(es) of the fix you need from master. They might be the same as in the fix pull request you are copying from, or they may be different if the pull request was closed with a squash. The best thing to do is to update your master branch, and get the hashes shown in your local git log:
   $ git log

3. Check out the release branch:
   $ git checkout open-release/XXX.master
$ git pull

4. Make a new branch from the release:
   $ git switch -c <YOURNAME>/<BRANCHNAME>

5. Cherry-pick the commits onto your branch. Do this for all your commits:
   $ git cherry-pick -x <COMMITHASH> ...

6. Push your branch:
   $ git push -u origin HEAD

7. Make a pull request from your branch, using open-release/XXX.master as the base. In your pull request description, mention the original pull request on master that you are copying, if you can.

8. Tag people for review. The pull request will be handled and merged like any other.

Backporting to a library repository

1. Ensure the change is already merged to master and released to PyPI/NPM.

2. Identify the top-level repository(s) that install this library – searching the package name in GitHub search can help. We’ll call these the dependent repositories.

3. Determine whether you should upgrade the named release to the latest library version or cut a backports release. If you’re unsure, the latter is always safer.

   1. Check whether the library already has a backports branch for this release: git log XXX-backports (where XXX is the release name). If so, you should use this branch. Jump directly to Cutting a backports release.

   2. For each dependent repository, identify the version of the library that is used on open-release/XXX.master – we’ll call that version A. If different versions of the library are used across top-level repositories, take the smallest A.

   3. Identify the latest version of the library, which should have your change on it. Let’s call it B.

   4. Look at the changeset between A and B. You can do this with GitHub: https://github.com/openedx/<library_repo>/compare/<A>...<B>.

   5. Do you feel comfortable backporting that entire changeset to each dependent repository in the named release?

      1. If so, jump to Upgrade the named release to the latest library version.

      2. If not, continue on to Cut a backports release.

4. Upgrade the named release to the latest library version:

   1. Open a PR in each dependent repository to upgrade the library to the latest version.

   2. Tag people for review & merge your PR(s).

   3. You’re all set!

5. Cut a backports release:

   1. Does the library have a backports branch already?

      1. If so, check it out and update it:

         $ git switch XXX-backports && git pull

      2. If not, check out a version of the library that is similar to what dependent repositories are using for this named release. From that version, create a named release branch: $ git switch -c XXX-backports && git push -u origin XXX-backports

   2. Create your own branch, based on the backports branch:
      $ git switch -x <YOURNAME>/<BRANCHNAME>

   3. Cherry-pick the commits onto your branch. Do this for all your commits:
      $ git cherry-pick -x <COMMITHASH> ...

   4. Update the version number to one that is similar to the current version on the backports branch, but not already taken by another release of the library. It should not exceed the latest library version number, because that would be confusing. Bumping the patch version is generally appropriate. Use your best judgement. We’ll call this the latest backports version.

   5. Push your branch:
      $ git push -u origin HEAD

   6. Make a pull request from your branch, using XXX-backports as the base. In your pull request description, mention the original pull request on master that you are copying, if you can.

   7. Tag people for review & merge your PR.

   8. Open a PR in each dependent repository to upgrade the library to the latest backports version. Tag people for review & merge your PR(s).

   9. You’re all set!

Making a change that is special to the named release

Sometimes a change is needed that doesn’t correspond to a change on master.

Changing a top-level repository

If your change should only be made on the named release branch of a top-level repository, there is nothing special to do. You make a change and create a pull request. The only difference is that the base of the pull request should be open-release/XXX.master instead of master. Explain in your pull request description why this should be a release-only change and doesn’t apply to master.

Changing a library repository

If your changes to a library should only be reflected in a named release, then refer to the Cutting a backports release step within the Backporting to a library repository process above. Instead of cherry-picking commits from master, though, just apply your special release-only changes and propose them in PR to the XXX-backports branch.

Explain in your pull request description why this should be a release-only change and doesn’t apply to master.