doc: change backporting guide with updated info

avivkeller · marco-ippolito · commit 4baa5c4d1021 · 2024-11-17T11:51:29.000+01:00
PR-URL: #53746 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
diff --git a/doc/contributing/backporting-to-release-lines.md b/doc/contributing/backporting-to-release-lines.md
@@ -2,136 +2,103 @@
 
 ## Staging branches
 
-Each release line has a staging branch that the releaser will use as a scratch
-pad while preparing a release. The branch name is formatted as follows:
-`vN.x-staging` where `N` is the major release number.
+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.
 
-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
-releaser will mark the pull request with a particular label for that release
-line (e.g. `backport-requested-vN.x`), specifying to our tooling that this
-pull request should not be included. The releaser will then add a comment
-requesting that a backport pull request be made.
+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.
 
-## What can be backported?
+## Criteria for backporting
 
-The "Current" release line is much more lenient than the LTS release lines in
-what can be landed. Our LTS release lines (see the [Release Plan][])
-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.
+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.
 
-## 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                                                                                       |
-| ----------------------- | ------------------------------------------------------------------------------------------------- |
-| backport-blocked-vN.x   | PRs that should land on the vN.x-staging branch but are blocked by another PR's pending backport. |
-| backport-open-vN.x      | Indicate that the PR has an open backport.                                                        |
-| backport-requested-vN.x | PRs awaiting manual backport to the vN.x-staging branch.                                          |
-| backported-to-vN.x      | PRs backported to the vN.x-staging branch.                                                        |
-| baking-for-lts          | PRs that need to wait before landing in a LTS release.                                            |
-| lts-watch-vN.x          | PRs that may need to be released in vN.x.                                                         |
-| vN.x                    | Issues that can be reproduced on vN.x or PRs targeting the vN.x-staging branch.                   |
+| 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).   |
 
-## 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`
-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
-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.
 
-### 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
-```
+   ```bash
+   # Example: Backport PR 123 to vN.x-staging
+   git node backport 123 --to=N
+   ```
 
-3. Jump to step 5 in the Manual section below
+3. Proceed to step 5 in the Manual section below.
 
-### Manually
+### Manual process
 
-1. Checkout the staging branch for the targeted release line.
+1. Checkout the `vN.x-staging` branch.
 
-2. Make sure that the local staging branch is up to date with the remote.
+2. Verify 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.
+3. Create a new branch based on `vN.x-staging`:
 
    ```bash
-   # Assuming your fork of Node.js is checked out in $NODE_DIR,
-   # the origin remote points to your fork, and the upstream remote points
-   # 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/
+   git fetch upstream vN.x-staging:vN.x-staging -f
+   git checkout -b backport-123-to-vN.x vN.x-staging
    ```
 
-4. After creating the branch, apply the changes to the branch. The cherry-pick
-   will likely fail due to conflicts. In that case, you will see something
-   like this:
-
-   ```console
-   # Say the $SHA is 773cdc31ef
-   $ git cherry-pick $SHA # Use your commit hash
-   error: could not apply 773cdc3... <commit title>
-   hint: after resolving the conflicts, mark the corrected paths
-   hint: with 'git add <paths>' or 'git rm <paths>'
-   hint: and commit the result with 'git commit'
+4. Cherry-pick the desired commit(s):
+
+   ```bash
+   git cherry-pick <commit hash>
    ```
 
-5. Make the required changes to remove the conflicts, add the files to the index
-   using `git add`, and then commit the changes. That can be done with
-   `git cherry-pick --continue`.
+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
    in the pull request. The `Backport-PR-URL` metadata does need to be added to
    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.
 
 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
-    with `backport-open-v20.x`.
-
-11. If during the review process conflicts arise, use the following to rebase:
-    `git pull --rebase upstream v20.x-staging`
-
-After the pull request lands, replace the `backport-open-v20.x` label on the
-original pull request with `backported-to-v20.x`.
+
+   * 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`.
 
 [Release Plan]: https://github.com/nodejs/Release#release-plan
 [Release Schedule]: https://github.com/nodejs/Release#release-schedule
 [`@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
-[`node-test-pull-request`]: https://ci.nodejs.org/job/node-test-pull-request/build
