github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-08-27 20:18:57 +00:00
Code Issues Projects Releases Wiki Activity

docs: backport guide improvements

Browse Source 
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 <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt 2019-08-29 16:13:36 +01:00
parent e0a537f661
commit 700d0c178f
1 changed files with 139 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
Backport-Guide.md
View File

@ -1,23 +1,96 @@
# Kata Containers stable backport workflow # 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) * [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 ## Introduction
PR or patchset in the Kata Containers repositories.
It does not cover all eventualities that might be encountered while performing This document provides a short guide explaining how to perform a backport.
a backport, and only documents one potential Git based workflow. It does Backporting refers to applying changes to a stable branch from a newer branch.
serve as a short introduction and reminder of the basic stable backport process. 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 ## Backport Workflow
The basic workflow involves creating a new local branch from the stable tree you The basic workflow involves:
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 following example shows a pseudo-backport of a PR from the `master` branch - Creating a new local branch from the stable tree you are targeting.
into the `stable-1.2` branch of the `runtime` repo. - 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: - 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 $ git fetch origin
``` ```
And check the list of current stable branches: Check the list of stable branches:
```bash ```bash
$ cd ${GOPATH}/src/github.com/kata-containers/runtime
$ git branch -r | grep origin/stable $ 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 ```bash
$ git checkout -b my_1.2_pr_backport origin/stable-1.2 $ 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. To list all commits in the `master` branch which are not in the `stable-1.2`
If you have the PR in a local branch you can substitute `master` for the name branch:
of that branch.
```bash ```bash
$ git log --oneline master $ git log --oneline --no-merges ..master
# And search for the SHA of the commits you wish to backport. ```
```
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: - Pull in your commits:
If you are pulling the commits in from the `master` branch, you can add the `-x` 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 argument to `git cherry-pick` to automatically add a reference in the
commit to the original commits. This is strongly recommended to aid traceability. 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 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 potentially adds references to SHAs that only exist in your local branch, which
is not be useful for future tracability. is not useful for future tracability.
It is also required that you add the `-s` signoff to the commits, if you did not It is also required that you add the `-s` signoff to the commits, if you did not
create the original commits. create the original commits.
```bash ```bash
$ git cherry-pick -x <commit>... $ git cherry-pick -x <commit>...
``` ```
You can cherry pick ranges of commits, etc. Please see the `git-cherry-pick(1)` > **Note:** You should only cherry pick the original commits - do **not**
man page for more information. > 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 You can cherry pick ranges of commits. Please see the `git-cherry-pick(1)`
> to the commits. They should re-use the `Fixes:` entry from the original commits, man page for more information.
> 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.
- 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 - Resolve any conflicts:
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 You might encounter conflicts during your cherry pick, which need to be resolved
applied. In this case, consider hand-adding the `master` SHA references and a note before you continue. Follow standard practices for Git conflict resolution, and see
that you resolved a conflict to the commit message. 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: - Test your changes:
Before you push your changes, you should test that they work and nothing has been 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. broken. No matter how small the change, running the test suite is always recommended.
### Raise a PR
- Push your branch to your GitHub repo: - Push your branch to your GitHub repo:
```bash ```bash
$ git push my_remote my_1.2_pr_backport $ git push my_remote my_1.2_pr_backport
``` ```
- Submit a PR from your branch to *the stable branch*: - 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 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 based your branch on and are submitting to. This *should* be the same as the
base branch for the PR. base branch for the PR.