From 700d0c178f3d9ed65cc1ebc97531411038014d37 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 29 Aug 2019 16:13:36 +0100 Subject: [PATCH] docs: backport guide improvements Add more detail to the backport guide including some ASCII graphics to demonstrate backporting and formatting improvements. Fixes: #110. Signed-off-by: James O. D. Hunt --- Backport-Guide.md | 193 +++++++++++++++++++++++++++++++++------------- 1 file changed, 139 insertions(+), 54 deletions(-) diff --git a/Backport-Guide.md b/Backport-Guide.md index 863c00756a..4905a37bd9 100644 --- a/Backport-Guide.md +++ b/Backport-Guide.md @@ -1,23 +1,96 @@ # Kata Containers stable backport workflow +* [Introduction](#introduction) +* [Assumptions](#assumptions) +* [Graphical overview of backporting](#graphical-overview-of-backporting) + * [Before the backport](#before-the-backport) + * [After the backport](#after-the-backport) * [Backport Workflow](#backport-workflow) + * [Setup](#setup) + * [Locate commits to cherry pick](#locate-commits-to-cherry-pick) + * [Apply the commits](#apply-the-commits) + * [Check the result](#check-the-result) + * [Raise a PR](#raise-a-pr) -This document provides a short guide on how to perform a stable backport of a -PR or patchset in the Kata Containers repositories. +## Introduction -It does not cover all eventualities that might be encountered while performing -a backport, and only documents one potential Git based workflow. It does -serve as a short introduction and reminder of the basic stable backport process. +This document provides a short guide explaining how to perform a backport. +Backporting refers to applying changes to a stable branch from a newer branch. +The changes comprise one or more commits in the form of a PR and the newer +branch is generally the `master` branch. + +Since new features are not added to stable branches, backported changes are +generally bug fixes and security fixes. See the +[stable branch strategy](https://github.com/kata-containers/documentation/blob/master/Stable-Branch-Strategy.md) +document for further details. + +> **Note:** This guide does not cover all eventualities that might be +> encountered while performing a backport, and only documents one potential +> Git based workflow. It does serve as a short introduction and reminder of +> the basic stable backport process. + +The two branches used in the examples in this guide are: + +- The `master` branch (which contains all commits). +- A `stable-1.2` branch which will be the target of the backport: commits will + be selectively "copied" ("cherry-picked") into this branch from the `master` branch. + +## Assumptions + +This document assumes an understanding of: + +- The `git(1)` tool. +- The [standard PR workflow](https://github.com/kata-containers/community/blob/master/CONTRIBUTING.md#normal-pr-workflow). +- The [stable branch strategy](https://github.com/kata-containers/documentation/blob/master/Stable-Branch-Strategy.md). + +## Graphical overview of backporting + +### Before the backport + +Imagine that initially both the `master` branch and the stable branch +(`stable-1.2`) contain only the commits `A`, `B` and `C`: + +``` + + (stable-1.2 branch) + / +A---B---C (master branch) +``` + +New commits (`D`, `E`, `F` and `G`) are added to the `master` branch: + +``` + + (stable-1.2 branch) + / +A---B---C---D---E---F---G (master branch) +``` + +Imagine that: + +- Commits `E` and `G` are bug or security fixes which need to be backported. +- Commits `D` and `F` are new features which must *not* be backported. + +### After the backport + +After the backporting: + +``` + +-----E-------G (stable-1.2 branch) + / ^ ^ +A---B---C---D---E---F---G (master branch) +``` + +After the backport, the `stable-1.2` branch contains commits `A`, `B` and +`C`, `E` and `G`. ## Backport Workflow -The basic workflow involves creating a new local branch from the stable tree you -are targeting, then cherry picking the commits from your master branch PR -onto that branch. You then submit your branch to GitHub as a PR against the -stable branch (and not the `master` branch). +The basic workflow involves: -The following example shows a pseudo-backport of a PR from the `master` branch -into the `stable-1.2` branch of the `runtime` repo. +- Creating a new local branch from the stable tree you are targeting. +- Selecting (or "cherry picking") the commits from your master branch PR into the stable branch. +- Submitting your branch to GitHub as a PR against the stable branch (not to the `master` branch). + +### Setup - Ensure your local repo is up to date: @@ -26,77 +99,89 @@ into the `stable-1.2` branch of the `runtime` repo. $ git fetch origin ``` - And check the list of current stable branches: + Check the list of stable branches: ```bash - $ cd ${GOPATH}/src/github.com/kata-containers/runtime $ git branch -r | grep origin/stable ``` -- Create your branch to work on: +- Create your branch to work on, based on the `stable-1.2` branch: ```bash $ git checkout -b my_1.2_pr_backport origin/stable-1.2 ``` -- Locate the commits you want to pull in: +### Locate commits to cherry pick - Here we look in the `master` branch, presuming the PR has been merged. - If you have the PR in a local branch you can substitute `master` for the name - of that branch. +To list all commits in the `master` branch which are not in the `stable-1.2` +branch: - ```bash - $ git log --oneline master - # And search for the SHA of the commits you wish to backport. - ``` +```bash +$ git log --oneline --no-merges ..master +``` + +Make a note of the SHA values for the commits in the PR to backport. + +> **Note:** If your PR is in a local branch, substitute `master` for the name +> of that branch. + +### Apply the commits - Pull in your commits: - If you are pulling the commits in from the `master` branch, you can add the `-x` - argument to `git cherry-pick` to automatically add a reference in the - commit to the original commits. This is strongly recommended to aid traceability. - If you pick the commits from your local branch do *not* use `-x`. This - potentially adds references to SHAs that only exist in your user branches, which - is not be useful for future tracability. + If you are pulling the commits in from the `master` branch, you can add the `-x` + argument to `git cherry-pick` to automatically add a reference in the + commit to the original commits. This is strongly recommended to aid traceability. + If you pick the commits from your local branch do *not* use `-x`; this + potentially adds references to SHAs that only exist in your local branch, which + is not useful for future tracability. - It is also required that you add the `-s` signoff to the commits, if you did not - create the original commits. + It is also required that you add the `-s` signoff to the commits, if you did not + create the original commits. - ```bash - $ git cherry-pick -x ... - ``` + ```bash + $ git cherry-pick -x ... + ``` - You can cherry pick ranges of commits, etc. Please see the `git-cherry-pick(1)` - man page for more information. + > **Note:** You should only cherry pick the original commits - do **not** + > cherry pick merge commits + > (see [Locate commits to cherry pick](#locate-commits-to-cherry-pick)). - > *Note:* You do not need to open a new `Issue` for or add an extra `Fixes: nnn` item - > to the commits. They should re-use the `Fixes:` entry from the original commits, - > so all related commits refer back to the common Issue. It does not matter that - > the original `Issue` is closed, the references still work correctly. + You can cherry pick ranges of commits. Please see the `git-cherry-pick(1)` + man page for more information. -- Resolve any conflicts, etc.: + > **Note:** You do not need to open a new `Issue` or add an extra `Fixes: nnn` item + > to the commits. They should re-use the `Fixes:` entry from the original commits, + > so all related commits refer back to the common Issue. It does not matter that + > the original `Issue` is closed, the references still work correctly. - You might encounter conflicts during your cherry pick, which need to be resolved - before you continue. Follow standard practices for Git conflict resolution, and see - the guidance printed by `git cherry-pick` on processing and applying those fixes. +- Resolve any conflicts: - If you hit a conflict, any effects of `-x` to `cherry-pick` might not be - applied. In this case, consider hand-adding the `master` SHA references and a note - that you resolved a conflict to the commit message. + You might encounter conflicts during your cherry pick, which need to be resolved + before you continue. Follow standard practices for Git conflict resolution, and see + the guidance printed by `git cherry-pick` on processing and applying those fixes. + + If you hit a conflict, any effects of `-x` to `cherry-pick` might not be + applied. In this case, consider hand-adding the `master` SHA references and a note + that you resolved a conflict to the commit message. + +### Check the result - Test your changes: - Before you push your changes, you should test that they work and nothing has been - broken. No matter how small the change, running the test suite is always recommended. + Before you push your changes, you should test that they work and nothing has been + broken. No matter how small the change, running the test suite is always recommended. + +### Raise a PR - Push your branch to your GitHub repo: - ```bash - $ git push my_remote my_1.2_pr_backport - ``` + ```bash + $ git push my_remote my_1.2_pr_backport + ``` - Submit a PR from your branch to *the stable branch*: - When you submit your PR on GitHub, make sure to choose the stable branch that you - based your branch on and are submitting to. This *should* be the same as the - base branch for the PR. + When you submit your PR on GitHub, make sure to choose the stable branch that you + based your branch on and are submitting to. This *should* be the same as the + base branch for the PR.