Skip to content

Latest commit

Β 

History

History
104 lines (69 loc) Β· 3.94 KB

backporting-to-release-lines.md

File metadata and controls

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