Repository navigation
Expand file tree
/
Copy pathbackporting-to-release-lines.md
More file actions
104 lines (69 loc) Β· 3.94 KB
/
Copy pathbackporting-to-release-lines.md
File metadata and controls
104 lines (69 loc) Β· 3.94 KB
Edit and raw actions
OlderNewer
Β
1
# How to backport a pull request to a release line
2
3
## Staging branches
4
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.
7
8
For active staging branches, refer to the [Release Schedule][].
9
10
## Identifying changes that require a backport
11
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.
15
16
## Criteria for backporting
17
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.
20
21
## Labeling backport issues and PRs
22
23
Use the following labels, with `N` in `vN.x` denoting the major release number:
24
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). |
34
35
## Submitting a backport pull request
36
37
For the following steps, let's assume that you need to backport PR `123`
38
to the vN.x release line. All commands will use the `vN.x-staging` branch
39
as the target branch. In order to submit a backport pull request to another
40
branch, simply replace `N` with the version number for the targeted release
41
line.
42
43
### Automated process
44
45
1. Ensure [`@node-core/utils`][] is installed.
46
47
2. Execute [`git node backport`][] command:
48
49
```bash
50
# Example: Backport PR 123 to vN.x-staging
51
git node backport 123 --to=N
52
```
53
54
3. Proceed to step 5 in the Manual section below.
55
56
### Manual process
57
58
1. Checkout the `vN.x-staging` branch.
59
60
2. Verify that the local staging branch is up to date with the remote.
61
62
3. Create a new branch based on `vN.x-staging`:
63
64
```bash
65
git fetch upstream vN.x-staging:vN.x-staging -f
66
git checkout -b backport-123-to-vN.x vN.x-staging
67
```
68
69
4. Cherry-pick the desired commit(s):
70
71
```bash
72
git cherry-pick <commit hash>
73
```
74
75
5. Resolve conflicts using `git add` and `git cherry-pick --continue`.
76
77
6. Leave the commit message as is. If you think it should be modified, comment
78
in the pull request. Do not manually add a `Backport-PR-URL` metadata entry.
79
This is automatically added later.
80
81
7. Verify that `make -j4 test` passes.
82
83
8. Push the changes to your fork.
84
85
9. Open a pull request:
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`.
100
101
[Release Plan]: https://github.com/nodejs/Release#release-plan
102
[Release Schedule]: https://github.com/nodejs/Release#release-schedule
103
[`@node-core/utils`]: https://github.com/nodejs/node-core-utils
104
[`git node backport`]: https://github.com/nodejs/node-core-utils/blob/main/docs/git-node.md#git-node-backport