From dfed2178826b541d67208135ccad57570ab2f2bc Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Tue, 15 Sep 2020 10:01:54 +0100 Subject: [PATCH] docs: Update for new porting process Explain the new porting process whereby all PRs must have a valid combination of porting labels to land. See: https://github.com/kata-containers/kata-containers/issues/634 Fixes: #172. Signed-off-by: James O. D. Hunt --- Backport-Guide.md | 12 +++ CONTRIBUTING.md | 212 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 224 insertions(+) diff --git a/Backport-Guide.md b/Backport-Guide.md index 40edd178b7..9d1ea3caa8 100644 --- a/Backport-Guide.md +++ b/Backport-Guide.md @@ -11,6 +11,7 @@ * [Apply the commits](#apply-the-commits) * [Check the result](#check-the-result) * [Raise a PR](#raise-a-pr) +* [Further information](#further-information) ## Introduction @@ -185,3 +186,14 @@ Make a note of the SHA values for the commits in the PR to backport. 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. + +- Add a special comment to the *original* PR with a reference to the backport + PR(s). See the [contributing guide](CONTRIBUTING.md#porting-comments) for + further information. + +- Add the `backport` label to the PR to denote it is a backport. + +## Further information + +For further information on porting, see the [contributing +guide](CONTRIBUTING.md#porting). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29fedce4d9..9ef02dfe9d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -502,6 +502,74 @@ $ popd >**Note:** The final `popd` is required to return to the top-level directory >from where other build rules can be executed. +## Porting + +Porting applies a patch set to an older ("backport") or a newer +("forward-port") branch or repository. + +Backporting is necessary to ensure that older -- but still maintained -- +releases benefit from bug fixes already applied to newer releases. + +Forward porting is necessary where there are multiple development streams and +bug fixes or new features have been applied to the older stream, but not the +newer one. + +> **Note:** +> +> Stable branches are considered maintenance branches, not development +> branches. Bug fixes must land in a newer development branch before landing +> in a stable branch to ensure the changes have been tested thoroughly before +> being applied to a stable release (maintenance) branch. + +Porting is performed with a new PR meaning porting PRs *must* have an +associated "parent" PR (the original bug fix or feature PR). + +Every PR must indicate whether it should be ported in either direction; +*backwards* (backport) or *forwards* (forward port). This is achieved by +adding up to two labels per PR which signal the porting requirements for the +PR. + +The [stable branch backports](#stable-branch-backports) section provides +information on the sorts of changes which should be backported. + +### Porting labels + +The table below lists all valid combinations of GitHub labels. Every PR must +be labelled as shown in the table row that most closely corresponds to the +type of PR the user is raising. + +> **Notes:** +> +> - The porting labels are enforced by a +> [GitHub action](https://github.com/kata-containers/.github/blob/master/scripts/pr-porting-checks.sh). +> This means that *PRs that do not have a valid set of porting labels cannot be merged*. +> - The "Common PR type" column in the table shows the most likely type of PR, but +> this is just a guide. +> - A `backport` or `forward-port` labelled PR **must** have an associated +> parent PR which caused the backport or forward port PR to be raised. + +| PR summary | Common PR type | Backport label | Forward port label | Notes | +|-|-|-|-|-| +| A "standalone" PR | Feature | `no-backport-needed` | `no-forward-port-needed` | PR does not need to be ported. For example, a PR used to add a new feature to the latest release. | +| PR that needs to be backported only | Bug fix | `needs-backport` | `no-forward-port-needed` | | +| PR that needs to be forward ported only | Bug fix or feature | `no-backport-needed` | `needs-forward-port` | | +| PR that needs to be ported backwards *and* forwards | Bug fix | `needs-backport` | `needs-forward-port` | For example a Kata 1.x PR that needs to be ported to Kata 2.0 *and* to one or more Kata 1.x stable branches. | +| A backport PR | Bug fix | `backport` | | PR to actually make the backport changes.

Must have an associated "parent" PR.

Title **must** contain original PRs title. | +| A forward port PR | Bug fix or feature | | `forward-port` | PR to actually make the forward port changes.

Must have an associated "parent" PR.

Title **must** contain original PRs title. | + +If you are not a member of the GitHub repository the PR is raised in, you may +not be able to see the GitHub labels. In this scenario, please add a comment +asking for the porting labels to be applied. + +Forward port and backport PRs by definition should not be raised in isolation: +there must be an existing PR that caused the porting PR to be raised. + +If you know whether a PR should be backported or forward ported, please add +a comment on the PR if you are unable to add the appropriate labels. If you do +not know whether a PR should be backported or forward ported, the community +will work with you to identify any porting requirements and to help with +porting activities. + ### Stable branch backports Kata Containers maintains a number of stable branch releases. Bug fixes to @@ -526,6 +594,150 @@ the original author of the PR is asked if they will submit the relevant backport PRs. For a quick guide on how to perform and submit a backport, see the [Backport Guide](Backport-Guide.md) in this repository. +### Porting issue numbers + +For ports that are within the same repository (for example a stable backport +to a 1.x PR), specify the same issue number as the original PR in the "fixes +comment". See the [patch format](#patch-format) section for further details. + +For ports in different repositories, create a new issue, referencing the +original issue URL in the issue text. + +### Porting comments + +Issues and PRs can only be linked if they are within the same repository. +Since Kata 2.x uses a new central repository, it is essential to add a special +comment to the **original PR** when new port PRs are created. + +| Port type | Port comment format | +|-|-| +| backport | `backport PR: ` | +| forward port| `forward port PR: ` | + +> **Notes:** +> +> - The special comments **must** appear at the start of a line. +> +> - The special comments are used by tooling to check that porting has been +> completed correctly. +> +> - Although these comments strictly make the `backport` and `forward-port` +> labels redundant, these labels are useful for general reporting since +> users can search for "all port PRs in a particular repository" for +> example. + +### Forward ports + +Forward ports tend to be much less common than backports. However, +consolidating a number of standalone repositories into a single repository for +the Kata 2.0 development effort introduced a potential forward port +requirement. At the time, both Kata 1.x and 2.0 versions were being developed +in parallel. This meant that lots of PRs raised in the Kata 1.x repositories +needed to be forward ported to the Kata 2.0 repository (since this was to be +the next major release and needed to contain all bug fixes and features where +possible). + +| Initial PR raised | PR type | Backport? | Forward port? | +|-|-|-|-| +| Particular 1.x repository | bug fix | stable branches | 2.0 repository | +| Particular 1.x repository | feature | | 2.0 repository | +| The 2.0 repository | bug fix | 1.x (and maybe stable branches) | - | +| The 2.0 repository | feature | | - | + +### Porting examples + +#### Backport and forward port example + +Imagine that you have just raised a new PR on a Kata 1.x repository. The PR +contains three commits: + +- A commit to fix a "typo" in a comment. +- A commit that changes the way a container is destroyed (and updates the tests). +- A commit that updates the documentation explaining the new contain + destruction behaviour. + +Since the PR is not adding any new functionality and since it is correcting +problems with existing code, it can be considered a bug fix PR. Bug fixes +should generally be backported. However, this PR was raised in a Kata 1.x +repository meaning it should also potentially be forward-ported to the Kata +2.0 repository. + +Looking at the tables in the [porting labels](#porting-labels) and the [stable +branch backports](#stable-branch-backports) sections shows that this PR needs +to be labelled with the following labels: + +- `needs-backport` +- `needs-forward-port` +- `stable-candidate` + +Once this PR is approved and is merged in the Kata 1.x repository, it should +now be backported and forward ported: + +- Backport: Raise new PRs on the currently maintained stable releases + + - These PRs should be labelled with the `backport` label. + - The commit message should mention the original PR. + - The commit message should reference the *original* issue number in the + ["fixes" comment](#patch-format). + +- Forward port: Raise a new PR on the Kata 2.0 repository + + - This PR should be labelled with the `forward-port` label. + - The commit message should mention the original PR. + - A new issue should be used for the PR and the original issue URL + referenced in the issue text. + +- Add [porting comments](#porting-comments) to the *original PR* with two comments, + one for each port: + + ``` + backport PR: https://github.com/kata-containers/runtime/pull/XXX + forward port PR: https://github.com/kata-containers/kata-containers/pull/YYY + ``` + +#### Double backport example + +Imagine that you have just raised a new PR on the Kata 2.x repository. The PR +fixes a nasty runtime bug, and adds some new unit tests to guarantee no future +regression. + +This is a pure bug fix PR. There is no "newer" branch or version, so it is not +possible to forward port. However, since the PR is an important bug fix, it +should be backported, both to Kata 1.x *and* the Kata 1.x stable branches. + +Looking at the tables in the [porting labels](#porting-labels) and the [stable +branch backports](#stable-branch-backports) sections shows that this PR needs +to be labelled with the following labels: + +- `needs-backport` +- `no-forward-port-needed` +- `stable-candidate` + +Once this PR is approved and is merged in the Kata 2.0 repository, it should +now be backported *twice*: + +- Kata 1.x: Raise a new PR on the Kata 1.x runtime repository + + - This PR should be labelled with the `backport` label. + - The commit message should mention the original PR. + +- Stable backports: Raise new PRs on each of the currently maintained stable + branches in the Kata 1.x runtime repository + + - These PRs should be labelled with the `backport` label. + - The commit message should mention the original PR. + - The commit message should reference the issue number used in the + ["fixes" comment](#patch-format) for the 1.x PR + (since that is in the same repository). + +- Add [porting comments](#porting-comments) to the *original PR* with two comments, + one for each port: + + ``` + backport PR: https://github.com/kata-containers/runtime/pull/XXX + backport PR: https://github.com/kata-containers/runtime/pull/YYY + ``` + ## Patch format ### General format