Skip to content

Commit 5e87577

Browse files
author
Aviv Keller
authored
doc: change backporting guide with updated info
PR-URL: #53746 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
1 parent ccc7ce0 commit 5e87577

File tree

1 file changed

+58
-91
lines changed

1 file changed

+58
-91
lines changed

‎doc/contributing/backporting-to-release-lines.md

+58-91
Original file line numberDiff line numberDiff line change
@@ -2,136 +2,103 @@
22

33
## Staging branches
44

5-
Each release line has a staging branch that the releaser will use as a scratch
6-
pad while preparing a release. The branch name is formatted as follows:
7-
`vN.x-staging` where `N` is the major release number.
5+
Each release line has a staging branch that serves as a workspace for preparing releases.
6+
The branch format is `vN.x-staging`, where `N` is the major release number.
87

9-
For the active staging branches see the [Release Schedule][].
8+
For active staging branches, refer to the [Release Schedule][].
109

11-
## What needs to be backported?
10+
## Identifying changes that require a backport
1211

13-
If a cherry-pick from `main` does not land cleanly on a staging branch, the
14-
releaser will mark the pull request with a particular label for that release
15-
line (e.g. `backport-requested-vN.x`), specifying to our tooling that this
16-
pull request should not be included. The releaser will then add a comment
17-
requesting that a backport pull request be made.
12+
If a cherry-pick from `main` doesn't apply cleanly on a staging branch, the pull request
13+
will be labeled for the release line (e.g., `backport-requested-vN.x`). This indicates
14+
that manual backporting is required.
1815

19-
## What can be backported?
16+
## Criteria for backporting
2017

21-
The "Current" release line is much more lenient than the LTS release lines in
22-
what can be landed. Our LTS release lines (see the [Release Plan][])
23-
require that commits mature in the Current release for at least 2 weeks before
24-
they can be landed in an LTS staging branch. Only after "maturation" will those
25-
commits be cherry-picked or backported.
18+
The "Current" release line is more flexible than LTS lines. LTS branches, detailed in the [Release Plan][],
19+
require commits to mature in the Current release for at least two weeks before backporting.
2620

27-
## How to label backport issues and PRs?
21+
## Labeling backport issues and PRs
2822

29-
For the following labels, the `N` in `vN.x` refers to the major release number.
23+
Use the following labels, with `N` in `vN.x` denoting the major release number:
3024

31-
| Label | Description |
32-
| ----------------------- | ------------------------------------------------------------------------------------------------- |
33-
| backport-blocked-vN.x | PRs that should land on the vN.x-staging branch but are blocked by another PR's pending backport. |
34-
| backport-open-vN.x | Indicate that the PR has an open backport. |
35-
| backport-requested-vN.x | PRs awaiting manual backport to the vN.x-staging branch. |
36-
| backported-to-vN.x | PRs backported to the vN.x-staging branch. |
37-
| baking-for-lts | PRs that need to wait before landing in a LTS release. |
38-
| lts-watch-vN.x | PRs that may need to be released in vN.x. |
39-
| vN.x | Issues that can be reproduced on vN.x or PRs targeting the vN.x-staging branch. |
25+
| Label | Description |
26+
| ----------------------- | ------------------------------------------------------------------- |
27+
| backport-blocked-vN.x | PRs for `vN.x-staging` blocked by pending backports from other PRs. |
28+
| backport-open-vN.x | Indicates an open backport for the PR. |
29+
| backport-requested-vN.x | PR awaiting manual backport to `vN.x-staging`. |
30+
| backported-to-vN.x | PR successfully backported to `vN.x-staging`. |
31+
| baking-for-lts | PRs awaiting LTS release after maturation in Current. |
32+
| lts-watch-vN.x | PRs possibly included in `vN.x` LTS releases. |
33+
| vN.x | Issues or PRs impacting `vN.x-staging` (or reproducible on vN.x). |
4034

41-
## How to submit a backport pull request
35+
## Submitting a backport pull request
4236

4337
For the following steps, let's assume that you need to backport PR `123`
44-
to the v20.x release line. All commands will use the `v20.x-staging` branch
38+
to the vN.x release line. All commands will use the `vN.x-staging` branch
4539
as the target branch. In order to submit a backport pull request to another
46-
branch, simply replace that with the staging branch for the targeted release
40+
branch, simply replace `N` with the version number for the targeted release
4741
line.
4842

49-
### Automated
43+
### Automated process
5044

51-
1. Make sure you have [`@node-core/utils`][] installed
45+
1. Ensure [`@node-core/utils`][] is installed.
5246

53-
2. Run the [`git node backport`][] command
47+
2. Execute [`git node backport`][] command:
5448

55-
```bash
56-
# Backport PR 123 to v20.x-staging
57-
git node backport 123 --to=20
58-
```
49+
```bash
50+
# Example: Backport PR 123 to vN.x-staging
51+
git node backport 123 --to=N
52+
```
5953

60-
3. Jump to step 5 in the Manual section below
54+
3. Proceed to step 5 in the Manual section below.
6155

62-
### Manually
56+
### Manual process
6357

64-
1. Checkout the staging branch for the targeted release line.
58+
1. Checkout the `vN.x-staging` branch.
6559

66-
2. Make sure that the local staging branch is up to date with the remote.
60+
2. Verify that the local staging branch is up to date with the remote.
6761

68-
3. Create a new branch off of the staging branch, as shown below.
62+
3. Create a new branch based on `vN.x-staging`:
6963

7064
```bash
71-
# Assuming your fork of Node.js is checked out in $NODE_DIR,
72-
# the origin remote points to your fork, and the upstream remote points
73-
# to git@github.com:nodejs/node.git
74-
cd $NODE_DIR
75-
# If v20.x-staging is checked out `pull` should be used instead of `fetch`
76-
git fetch upstream v20.x-staging:v20.x-staging -f
77-
# Assume we want to backport PR #10157
78-
git checkout -b backport-10157-to-v20.x v20.x-staging
79-
# Ensure there are no test artifacts from previous builds
80-
# Note that this command deletes all files and directories
81-
# not under revision control below the ./test directory.
82-
# It is optional and should be used with caution.
83-
git clean -xfd ./test/
65+
git fetch upstream vN.x-staging:vN.x-staging -f
66+
git checkout -b backport-123-to-vN.x vN.x-staging
8467
```
8568

86-
4. After creating the branch, apply the changes to the branch. The cherry-pick
87-
will likely fail due to conflicts. In that case, you will see something
88-
like this:
89-
90-
```console
91-
# Say the $SHA is 773cdc31ef
92-
$ git cherry-pick $SHA # Use your commit hash
93-
error: could not apply 773cdc3... <commit title>
94-
hint: after resolving the conflicts, mark the corrected paths
95-
hint: with 'git add <paths>' or 'git rm <paths>'
96-
hint: and commit the result with 'git commit'
69+
4. Cherry-pick the desired commit(s):
70+
71+
```bash
72+
git cherry-pick <commit hash>
9773
```
9874

99-
5. Make the required changes to remove the conflicts, add the files to the index
100-
using `git add`, and then commit the changes. That can be done with
101-
`git cherry-pick --continue`.
75+
5. Resolve conflicts using `git add` and `git cherry-pick --continue`.
10276

10377
6. Leave the commit message as is. If you think it should be modified, comment
10478
in the pull request. The `Backport-PR-URL` metadata does need to be added to
10579
the commit, but this will be done later.
10680

107-
7. Make sure `make -j4 test` passes.
81+
7. Verify that `make -j4 test` passes.
10882

10983
8. Push the changes to your fork.
11084

11185
9. Open a pull request:
112-
1. Be sure to target the `v20.x-staging` branch in the pull request.
113-
2. Include the backport target in the pull request title in the following
114-
format: `[v20.x backport] <commit title>`.
115-
Example: `[v20.x backport] process: improve performance of nextTick`
116-
3. Check the checkbox labeled "Allow edits and access to secrets by
117-
maintainers".
118-
4. In the description add a reference to the original pull request.
119-
5. Amend the commit message and include a `Backport-PR-URL:` metadata and
120-
re-push the change to your fork.
121-
6. Run a [`node-test-pull-request`][] CI job (with `REBASE_ONTO` set to the
122-
default `<pr base branch>`)
123-
124-
10. Replace the `backport-requested-v20.x` label on the original pull request
125-
with `backport-open-v20.x`.
126-
127-
11. If during the review process conflicts arise, use the following to rebase:
128-
`git pull --rebase upstream v20.x-staging`
129-
130-
After the pull request lands, replace the `backport-open-v20.x` label on the
131-
original pull request with `backported-to-v20.x`.
86+
87+
* Target `vN.x-staging`.
88+
* Title format: `[vN.x backport] <commit title>` (e.g., `[v20.x backport] process: improve performance of nextTick`).
89+
* Reference the original PR in the description.
90+
91+
10. Update the `backport-requested-vN.x` label on the original pull request to `backport-open-vN.x`.
92+
93+
11. If conflicts arise during the review process, the following command be used to rebase:
94+
95+
```bash
96+
git pull --rebase upstream vN.x-staging
97+
```
98+
99+
Once merged, update the original PR's label from `backport-open-vN.x` to `backported-to-vN.x`.
132100
133101
[Release Plan]: https://github.com/nodejs/Release#release-plan
134102
[Release Schedule]: https://github.com/nodejs/Release#release-schedule
135103
[`@node-core/utils`]: https://github.com/nodejs/node-core-utils
136104
[`git node backport`]: https://github.com/nodejs/node-core-utils/blob/main/docs/git-node.md#git-node-backport
137-
[`node-test-pull-request`]: https://ci.nodejs.org/job/node-test-pull-request/build

0 commit comments

Comments
 (0)