Backporting commits to a release branch

Backporting commits to a release branch

About backporting

Backporting is when you apply a commit from main to a release branch, for example 2.1. We use the git cherry-pick command to apply the commit to the release branch.

Brief overview of the backporting process

1. Identify the commit(s) in main that you need to apply to the release branch.

2. Checkout a new backport branch locally from the upstream release branch.

3. Cherry-pick the commit(s) onto the backport branch. If you need to cherry-pick more than one commit, start with the oldest commit.

4. Push the local backport branch to your fork.

5. Create a pull request to merge the backport branch on your fork into the upstream release branch.

For a worked example of backporting a commit from main to the 2.0-ea release branch, see this google doc.

Procedure

1. Identify the commit that you want to backport to the release branch. The code below shows the most recent commits in the master branch. If you wanted to backport PR#219, the commit to backport is 2c3ad06.

   $ git log --oneline -n 2 upstream/main
   2c3ad06 Platform - Fixes to platform upgrade docs (#219)
   d5ab21c Merge pull request #215 from TarikFD/aap-1492

2. Fetch the latest changes from the upstream repo.

   git fetch upstream

3. Sync your local main branch with the upstream repo. See Keeping your repository up to date.

4. Create a new local backport branch from the upstream release branch.

   git checkout -b <backport-branch> upstream/<release>

   When naming the backport branch, it’s useful to include the release branch name and the PR number that you want to backport. For instance, if you were backporting the commit for PR#219 to the 2.1 branch, you could call the branch backport-2.1-209. This is not mandatory, but it’s useful if you are backporting multiple PRs to multiple release branches.

   $ git checkout -b backport-<release>-<PR#> upstream/<release>
   $ git checkout -b backport-2.1-209 upstream/2.1

5. Checkout the new local backport branch. Cherry-pick the commit that you identified in step 1 to the backport branch.

   $ git checkout <backport-branch>
   $ git cherry-pick <commit>

   $ git checkout backport-2.1-209
   $ git cherry-pick 2c3ad06

   If you need to add more than one commit to your backport branch, cherry-pick the oldest commit first.

6. Build the docs on the backport branch and verify that the docs look ok.

7. Push the backport branch to origin (your fork).

   git push origin backport-2.1-209

8. Create a backport pull request on GitHub from origin/<backport-branch-name> on your fork to upstream/release-branch.

   Be careful here: GitHub defaults to setting main as the target branch in a new PR.

9. Check that you have selected the correct upstream release branch as the target branch for your backport PR.

10. Request a review. The reviewer can checkout a copy of the backport PR locally and build the docs to validate your changes.

11. After approval from a reviewer, the pull request is ready to merge.