github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-08-25 19:21:53 +00:00
Code Issues Projects Releases Wiki Activity

docs: Update for new porting process

Browse Source 
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 <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt 2020-09-15 10:01:54 +01:00
parent c44fedccd0
commit dfed217882
2 changed files with 224 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
Backport-Guide.md
View File

@ -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).

212
CONTRIBUTING.md
View File

@ -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.<br/><br/>Must have an associated "parent" PR.<br/><br/>Title **must** contain original PRs title. |
| A forward port PR | Bug fix or feature | | `forward-port` | PR to actually make the forward port changes.<br/><br/>Must have an associated "parent" PR.<br/><br/>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: <backport-pr-url>` |
| forward port| `forward port PR: <forward-port-pr-url>` |
> **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