mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-08-28 12:31:04 +00:00
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 <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt
parent
c44fedccd0
commit
dfed217882
@ -11,6 +11,7 @@
|
|||||||
* [Apply the commits](#apply-the-commits)
|
* [Apply the commits](#apply-the-commits)
|
||||||
* [Check the result](#check-the-result)
|
* [Check the result](#check-the-result)
|
||||||
* [Raise a PR](#raise-a-pr)
|
* [Raise a PR](#raise-a-pr)
|
||||||
|
* [Further information](#further-information)
|
||||||
|
|
||||||
## Introduction
|
## 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
|
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.
|
||||||
|
|
||||||
|
- 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
212
CONTRIBUTING.md
@ -502,6 +502,74 @@ $ popd
|
|||||||
>**Note:** The final `popd` is required to return to the top-level directory
|
>**Note:** The final `popd` is required to return to the top-level directory
|
||||||
>from where other build rules can be executed.
|
>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
|
### Stable branch backports
|
||||||
|
|
||||||
Kata Containers maintains a number of stable branch releases. Bug fixes to
|
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
|
backport PRs. For a quick guide on how to perform and submit a backport, see
|
||||||
the [Backport Guide](Backport-Guide.md) in this repository.
|
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
|
## Patch format
|
||||||
|
|
||||||
### General format
|
### General format
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user