1# How to backport a pull request to a release line 2 3## Staging branches 4 5Each release line has a staging branch that the releaser will use as a scratch 6pad while preparing a release. The branch name is formatted as follows: 7`vN.x-staging` where `N` is the major release number. 8 9For the active staging branches see the [Release Schedule][]. 10 11## What needs to be backported? 12 13If a cherry-pick from `main` does not land cleanly on a staging branch, the 14releaser will mark the pull request with a particular label for that release 15line (e.g. `backport-requested-vN.x`), specifying to our tooling that this 16pull request should not be included. The releaser will then add a comment 17requesting that a backport pull request be made. 18 19## What can be backported? 20 21The "Current" release line is much more lenient than the LTS release lines in 22what can be landed. Our LTS release lines (see the [Release Plan][]) 23require that commits mature in the Current release for at least 2 weeks before 24they can be landed in an LTS staging branch. Only after "maturation" will those 25commits be cherry-picked or backported. 26 27## How to label backport issues and PRs? 28 29For the following labels, the `N` in `vN.x` refers to the major release number. 30 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. | 40 41## How to submit a backport pull request 42 43For the following steps, let's assume that a backport is needed for the v10.x 44release line. All commands will use the `v10.x-staging` branch as the target 45branch. In order to submit a backport pull request to another branch, simply 46replace that with the staging branch for the targeted release line. 47 481. Checkout the staging branch for the targeted release line. 49 502. Make sure that the local staging branch is up to date with the remote. 51 523. Create a new branch off of the staging branch, as shown below. 53 54 ```bash 55 # Assuming your fork of Node.js is checked out in $NODE_DIR, 56 # the origin remote points to your fork, and the upstream remote points 57 # to git@github.com:nodejs/node.git 58 cd $NODE_DIR 59 # If v10.x-staging is checked out `pull` should be used instead of `fetch` 60 git fetch upstream v10.x-staging:v10.x-staging -f 61 # Assume we want to backport PR #10157 62 git checkout -b backport-10157-to-v10.x v10.x-staging 63 # Ensure there are no test artifacts from previous builds 64 # Note that this command deletes all files and directories 65 # not under revision control below the ./test directory. 66 # It is optional and should be used with caution. 67 git clean -xfd ./test/ 68 ``` 69 704. After creating the branch, apply the changes to the branch. The cherry-pick 71 will likely fail due to conflicts. In that case, you will see something 72 like this: 73 74 ```console 75 # Say the $SHA is 773cdc31ef 76 $ git cherry-pick $SHA # Use your commit hash 77 error: could not apply 773cdc3... <commit title> 78 hint: after resolving the conflicts, mark the corrected paths 79 hint: with 'git add <paths>' or 'git rm <paths>' 80 hint: and commit the result with 'git commit' 81 ``` 82 835. Make the required changes to remove the conflicts, add the files to the index 84 using `git add`, and then commit the changes. That can be done with 85 `git cherry-pick --continue`. 86 876. Leave the commit message as is. If you think it should be modified, comment 88 in the pull request. The `Backport-PR-URL` metadata does need to be added to 89 the commit, but this will be done later. 90 917. Make sure `make -j4 test` passes. 92 938. Push the changes to your fork. 94 959. Open a pull request: 96 1. Be sure to target the `v10.x-staging` branch in the pull request. 97 2. Include the backport target in the pull request title in the following 98 format: `[v10.x backport] <commit title>`. 99 Example: `[v10.x backport] process: improve performance of nextTick` 100 3. Check the checkbox labeled "Allow edits and access to secrets by 101 maintainers". 102 4. In the description add a reference to the original pull request. 103 5. Amend the commit message and include a `Backport-PR-URL:` metadata and 104 re-push the change to your fork. 105 6. Run a [`node-test-pull-request`][] CI job (with `REBASE_ONTO` set to the 106 default `<pr base branch>`) 107 10810. Replace the `backport-requested-v10.x` label on the original pull request 109 with `backport-open-v10.x`. 110 11111. If during the review process conflicts arise, use the following to rebase: 112 `git pull --rebase upstream v10.x-staging` 113 114After the pull request lands, replace the `backport-open-v10.x` label on the 115original pull request with `backported-to-v10.x`. 116 117[Release Plan]: https://github.com/nodejs/Release#release-plan 118[Release Schedule]: https://github.com/nodejs/Release#release-schedule 119[`node-test-pull-request`]: https://ci.nodejs.org/job/node-test-pull-request/build 120