2021-03-06 11:03:49 +05:30
|
|
|
# How to backport a pull request to a release line
|
2017-02-01 05:56:41 -06:00
|
|
|
|
|
|
|
## Staging branches
|
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
Each release line has a staging branch that serves as a workspace for preparing releases.
|
|
|
|
The branch format is `vN.x-staging`, where `N` is the major release number.
|
2017-02-01 05:56:41 -06:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
For active staging branches, refer to the [Release Schedule][].
|
2017-02-01 05:56:41 -06:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
## Identifying changes that require a backport
|
2017-02-01 05:56:41 -06:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
If a cherry-pick from `main` doesn't apply cleanly on a staging branch, the pull request
|
|
|
|
will be labeled for the release line (e.g., `backport-requested-vN.x`). This indicates
|
|
|
|
that manual backporting is required.
|
2017-02-01 05:56:41 -06:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
## Criteria for backporting
|
2017-02-01 05:56:41 -06:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
The "Current" release line is more flexible than LTS lines. LTS branches, detailed in the [Release Plan][],
|
|
|
|
require commits to mature in the Current release for at least two weeks before backporting.
|
2017-02-01 05:56:41 -06:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
## Labeling backport issues and PRs
|
2021-10-19 08:38:53 -07:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
Use the following labels, with `N` in `vN.x` denoting the major release number:
|
2021-10-19 08:38:53 -07:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
| Label | Description |
|
|
|
|
| ----------------------- | ------------------------------------------------------------------- |
|
|
|
|
| backport-blocked-vN.x | PRs for `vN.x-staging` blocked by pending backports from other PRs. |
|
|
|
|
| backport-open-vN.x | Indicates an open backport for the PR. |
|
|
|
|
| backport-requested-vN.x | PR awaiting manual backport to `vN.x-staging`. |
|
|
|
|
| backported-to-vN.x | PR successfully backported to `vN.x-staging`. |
|
|
|
|
| baking-for-lts | PRs awaiting LTS release after maturation in Current. |
|
|
|
|
| lts-watch-vN.x | PRs possibly included in `vN.x` LTS releases. |
|
|
|
|
| vN.x | Issues or PRs impacting `vN.x-staging` (or reproducible on vN.x). |
|
2021-10-19 08:38:53 -07:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
## Submitting a backport pull request
|
2017-02-01 05:56:41 -06:00
|
|
|
|
2023-09-24 11:23:18 +03:00
|
|
|
For the following steps, let's assume that you need to backport PR `123`
|
2024-09-18 03:52:30 -04:00
|
|
|
to the vN.x release line. All commands will use the `vN.x-staging` branch
|
2023-09-24 11:23:18 +03:00
|
|
|
as the target branch. In order to submit a backport pull request to another
|
2024-09-18 03:52:30 -04:00
|
|
|
branch, simply replace `N` with the version number for the targeted release
|
2023-09-24 11:23:18 +03:00
|
|
|
line.
|
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
### Automated process
|
2023-09-24 11:23:18 +03:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
1. Ensure [`@node-core/utils`][] is installed.
|
2023-09-24 11:23:18 +03:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
2. Execute [`git node backport`][] command:
|
2023-09-24 11:23:18 +03:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
```bash
|
|
|
|
# Example: Backport PR 123 to vN.x-staging
|
|
|
|
git node backport 123 --to=N
|
|
|
|
```
|
2023-09-24 11:23:18 +03:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
3. Proceed to step 5 in the Manual section below.
|
2023-09-24 11:23:18 +03:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
### Manual process
|
2017-02-01 05:56:41 -06:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
1. Checkout the `vN.x-staging` branch.
|
2021-10-06 21:40:23 -07:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
2. Verify that the local staging branch is up to date with the remote.
|
2021-10-06 21:40:23 -07:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
3. Create a new branch based on `vN.x-staging`:
|
2017-02-01 05:56:41 -06:00
|
|
|
|
2021-10-06 21:40:23 -07:00
|
|
|
```bash
|
2024-09-18 03:52:30 -04:00
|
|
|
git fetch upstream vN.x-staging:vN.x-staging -f
|
|
|
|
git checkout -b backport-123-to-vN.x vN.x-staging
|
2021-10-06 21:40:23 -07:00
|
|
|
```
|
2017-02-01 05:56:41 -06:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
4. Cherry-pick the desired commit(s):
|
|
|
|
|
|
|
|
```bash
|
|
|
|
git cherry-pick <commit hash>
|
2021-10-06 21:40:23 -07:00
|
|
|
```
|
2017-02-01 05:56:41 -06:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
5. Resolve conflicts using `git add` and `git cherry-pick --continue`.
|
2021-10-06 21:40:23 -07:00
|
|
|
|
2017-06-17 16:09:54 -04:00
|
|
|
6. Leave the commit message as is. If you think it should be modified, comment
|
2020-04-26 16:03:12 -07:00
|
|
|
in the pull request. The `Backport-PR-URL` metadata does need to be added to
|
2018-10-16 13:03:34 -07:00
|
|
|
the commit, but this will be done later.
|
2021-10-06 21:40:23 -07:00
|
|
|
|
2024-09-18 03:52:30 -04:00
|
|
|
7. Verify that `make -j4 test` passes.
|
2021-10-06 21:40:23 -07:00
|
|
|
|
2020-04-26 16:03:12 -07:00
|
|
|
8. Push the changes to your fork.
|
2021-10-06 21:40:23 -07:00
|
|
|
|
2017-06-17 16:09:54 -04:00
|
|
|
9. Open a pull request:
|
2024-09-18 03:52:30 -04:00
|
|
|
|
|
|
|
* Target `vN.x-staging`.
|
|
|
|
* Title format: `[vN.x backport] <commit title>` (e.g., `[v20.x backport] process: improve performance of nextTick`).
|
|
|
|
* Reference the original PR in the description.
|
|
|
|
|
|
|
|
10. Update the `backport-requested-vN.x` label on the original pull request to `backport-open-vN.x`.
|
|
|
|
|
|
|
|
11. If conflicts arise during the review process, the following command be used to rebase:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
git pull --rebase upstream vN.x-staging
|
|
|
|
```
|
|
|
|
|
|
|
|
Once merged, update the original PR's label from `backport-open-vN.x` to `backported-to-vN.x`.
|
2017-06-17 16:09:54 -04:00
|
|
|
|
2017-09-29 05:37:51 +03:00
|
|
|
[Release Plan]: https://github.com/nodejs/Release#release-plan
|
2020-11-02 19:45:47 +09:00
|
|
|
[Release Schedule]: https://github.com/nodejs/Release#release-schedule
|
2023-09-25 13:48:03 +02:00
|
|
|
[`@node-core/utils`]: https://github.com/nodejs/node-core-utils
|
2023-09-24 11:23:18 +03:00
|
|
|
[`git node backport`]: https://github.com/nodejs/node-core-utils/blob/main/docs/git-node.md#git-node-backport
|