Nodejs/node
1
0
Fork 0
mirror of https://github.com/nodejs/node.git synced 2024-11-21 10:59:27 +00:00
Code Issues Actions 25 Packages Projects Releases Wiki Activity

doc: change backporting guide with updated info

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/53746
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
This commit is contained in:
Aviv Keller 2024-09-18 03:52:30 -04:00 committed by GitHub
parent ccc7ce09f2
commit 5e87577b4f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 60 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
doc/contributing/backporting-to-release-lines.md
View File

@ -2,136 +2,103 @@
## Staging branches ## Staging branches
Each release line has a staging branch that the releaser will use as a scratch Each release line has a staging branch that serves as a workspace for preparing releases.
pad while preparing a release. The branch name is formatted as follows: The branch format is `vN.x-staging`, where `N` is the major release number.
`vN.x-staging` where `N` is the major release number.
For the active staging branches see the [Release Schedule][]. For active staging branches, refer to the [Release Schedule][].
## What needs to be backported? ## Identifying changes that require a backport
If a cherry-pick from `main` does not land cleanly on a staging branch, the If a cherry-pick from `main` doesn't apply cleanly on a staging branch, the pull request
releaser will mark the pull request with a particular label for that release will be labeled for the release line (e.g., `backport-requested-vN.x`). This indicates
line (e.g. `backport-requested-vN.x`), specifying to our tooling that this that manual backporting is required.
pull request should not be included. The releaser will then add a comment
requesting that a backport pull request be made.
## What can be backported? ## Criteria for backporting
The "Current" release line is much more lenient than the LTS release lines in The "Current" release line is more flexible than LTS lines. LTS branches, detailed in the [Release Plan][],
what can be landed. Our LTS release lines (see the [Release Plan][]) require commits to mature in the Current release for at least two weeks before backporting.
require that commits mature in the Current release for at least 2 weeks before
they can be landed in an LTS staging branch. Only after "maturation" will those
commits be cherry-picked or backported.
## How to label backport issues and PRs? ## Labeling backport issues and PRs
For the following labels, the `N` in `vN.x` refers to the major release number. Use the following labels, with `N` in `vN.x` denoting the major release number:
| Label | Description | | Label | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------- | | ----------------------- | ------------------------------------------------------------------- |
| backport-blocked-vN.x | PRs that should land on the vN.x-staging branch but are blocked by another PR's pending backport. | | backport-blocked-vN.x | PRs for `vN.x-staging` blocked by pending backports from other PRs. |
| backport-open-vN.x | Indicate that the PR has an open backport. | | backport-open-vN.x | Indicates an open backport for the PR. |
| backport-requested-vN.x | PRs awaiting manual backport to the vN.x-staging branch. | | backport-requested-vN.x | PR awaiting manual backport to `vN.x-staging`. |
| backported-to-vN.x | PRs backported to the vN.x-staging branch. | | backported-to-vN.x | PR successfully backported to `vN.x-staging`. |
| baking-for-lts | PRs that need to wait before landing in a LTS release. | | baking-for-lts | PRs awaiting LTS release after maturation in Current. |
| lts-watch-vN.x | PRs that may need to be released in vN.x. | | lts-watch-vN.x | PRs possibly included in `vN.x` LTS releases. |
| vN.x | Issues that can be reproduced on vN.x or PRs targeting the vN.x-staging branch. | | vN.x | Issues or PRs impacting `vN.x-staging` (or reproducible on vN.x). |
## How to submit a backport pull request ## Submitting a backport pull request
For the following steps, let's assume that you need to backport PR `123` For the following steps, let's assume that you need to backport PR `123`
to the v20.x release line. All commands will use the `v20.x-staging` branch to the vN.x release line. All commands will use the `vN.x-staging` branch
as the target branch. In order to submit a backport pull request to another as the target branch. In order to submit a backport pull request to another
branch, simply replace that with the staging branch for the targeted release branch, simply replace `N` with the version number for the targeted release
line. line.
### Automated ### Automated process
1. Make sure you have [`@node-core/utils`][] installed 1. Ensure [`@node-core/utils`][] is installed.
2. Run the [`git node backport`][] command 2. Execute [`git node backport`][] command:
```bash
# Backport PR 123 to v20.x-staging
git node backport 123 --to=20
```
3. Jump to step 5 in the Manual section below
### Manually
1. Checkout the staging branch for the targeted release line.
2. Make sure that the local staging branch is up to date with the remote.
3. Create a new branch off of the staging branch, as shown below.
```bash ```bash
# Assuming your fork of Node.js is checked out in $NODE_DIR, # Example: Backport PR 123 to vN.x-staging
# the origin remote points to your fork, and the upstream remote points git node backport 123 --to=N
# to git@github.com:nodejs/node.git
cd $NODE_DIR
# If v20.x-staging is checked out `pull` should be used instead of `fetch`
git fetch upstream v20.x-staging:v20.x-staging -f
# Assume we want to backport PR #10157
git checkout -b backport-10157-to-v20.x v20.x-staging
# Ensure there are no test artifacts from previous builds
# Note that this command deletes all files and directories
# not under revision control below the ./test directory.
# It is optional and should be used with caution.
git clean -xfd ./test/
``` ```
4. After creating the branch, apply the changes to the branch. The cherry-pick 3. Proceed to step 5 in the Manual section below.
will likely fail due to conflicts. In that case, you will see something
like this:
```console ### Manual process
# Say the $SHA is 773cdc31ef
$ git cherry-pick $SHA # Use your commit hash 1. Checkout the `vN.x-staging` branch.
error: could not apply 773cdc3... <commit title>
hint: after resolving the conflicts, mark the corrected paths 2. Verify that the local staging branch is up to date with the remote.
hint: with 'git add <paths>' or 'git rm <paths>'
hint: and commit the result with 'git commit' 3. Create a new branch based on `vN.x-staging`:
```bash
git fetch upstream vN.x-staging:vN.x-staging -f
git checkout -b backport-123-to-vN.x vN.x-staging
``` ```
5. Make the required changes to remove the conflicts, add the files to the index 4. Cherry-pick the desired commit(s):
using `git add`, and then commit the changes. That can be done with
`git cherry-pick --continue`. ```bash
git cherry-pick <commit hash>
```
5. Resolve conflicts using `git add` and `git cherry-pick --continue`.
6. Leave the commit message as is. If you think it should be modified, comment 6. Leave the commit message as is. If you think it should be modified, comment
in the pull request. The `Backport-PR-URL` metadata does need to be added to in the pull request. The `Backport-PR-URL` metadata does need to be added to
the commit, but this will be done later. the commit, but this will be done later.
7. Make sure `make -j4 test` passes. 7. Verify that `make -j4 test` passes.
8. Push the changes to your fork. 8. Push the changes to your fork.
9. Open a pull request: 9. Open a pull request:
1. Be sure to target the `v20.x-staging` branch in the pull request.
2. Include the backport target in the pull request title in the following
format: `[v20.x backport] <commit title>`.
Example: `[v20.x backport] process: improve performance of nextTick`
3. Check the checkbox labeled "Allow edits and access to secrets by
maintainers".
4. In the description add a reference to the original pull request.
5. Amend the commit message and include a `Backport-PR-URL:` metadata and
re-push the change to your fork.
6. Run a [`node-test-pull-request`][] CI job (with `REBASE_ONTO` set to the
default `<pr base branch>`)
10. Replace the `backport-requested-v20.x` label on the original pull request * Target `vN.x-staging`.
with `backport-open-v20.x`. * Title format: `[vN.x backport] <commit title>` (e.g., `[v20.x backport] process: improve performance of nextTick`).
* Reference the original PR in the description.
11. If during the review process conflicts arise, use the following to rebase: 10. Update the `backport-requested-vN.x` label on the original pull request to `backport-open-vN.x`.
`git pull --rebase upstream v20.x-staging`
After the pull request lands, replace the `backport-open-v20.x` label on the 11. If conflicts arise during the review process, the following command be used to rebase:
original pull request with `backported-to-v20.x`.
```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`.
[Release Plan]: https://github.com/nodejs/Release#release-plan [Release Plan]: https://github.com/nodejs/Release#release-plan
[Release Schedule]: https://github.com/nodejs/Release#release-schedule [Release Schedule]: https://github.com/nodejs/Release#release-schedule
[`@node-core/utils`]: https://github.com/nodejs/node-core-utils [`@node-core/utils`]: https://github.com/nodejs/node-core-utils
[`git node backport`]: https://github.com/nodejs/node-core-utils/blob/main/docs/git-node.md#git-node-backport [`git node backport`]: https://github.com/nodejs/node-core-utils/blob/main/docs/git-node.md#git-node-backport
[`node-test-pull-request`]: https://ci.nodejs.org/job/node-test-pull-request/build