Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: change backporting guide with updated info #53746

Merged
merged 10 commits into from
Sep 18, 2024
Merged

doc: change backporting guide with updated info #53746

Changes from 3 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
fb786e7
doc: change backporting guide with updated info
avivkeller Jul 6, 2024
02c18ae
lint
avivkeller Jul 6, 2024
6f1d673
Update backporting-to-release-lines.md
avivkeller Jul 6, 2024
f13012f
apply suggested changes
avivkeller Jul 8, 2024
8028dd6
Update backporting-to-release-lines.md
avivkeller Jul 8, 2024
fbd0135
Update backporting-to-release-lines.md
avivkeller Jul 8, 2024
bbbc64f
Update backporting-to-release-lines.md
avivkeller Jul 8, 2024
4fbd3fe
Update backporting-to-release-lines.md
avivkeller Jul 8, 2024
324bb6d
Update backporting-to-release-lines.md
avivkeller Jul 12, 2024
1e0f0ba
Update backporting-to-release-lines.md
avivkeller Jul 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 56 additions & 94 deletions doc/contributing/backporting-to-release-lines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,133 +2,95 @@

## 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 backport needs
aduh95 marked this conversation as resolved.
Show resolved Hide resolved

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 merge cleanly with a staging branch, the pull request
avivkeller marked this conversation as resolved.
Show resolved Hide resolved
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
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
line.
Follow these steps to backport a PR (e.g., #123) to the `vN.x` release line:
avivkeller marked this conversation as resolved.
Show resolved Hide resolved

### 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. Check out the `vN.x-staging` branch.
avivkeller marked this conversation as resolved.
Show resolved Hide resolved

2. Make sure that the local staging branch is up to date with the remote.
2. Update the local staging branch from the remote.
avivkeller marked this conversation as resolved.
Show resolved Hide resolved

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 checkout -b backport-123-to-v20.x v20.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:
4. Resolve conflicts during cherry-pick:
avivkeller marked this conversation as resolved.
Show resolved Hide resolved

```console
avivkeller marked this conversation as resolved.
Show resolved Hide resolved
# 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'
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.
6. Keep the commit message unchanged or modify as needed.
avivkeller marked this conversation as resolved.
Show resolved Hide resolved

7. Make sure `make -j4 test` passes.
7. Verify with `make -j4 test`.
avivkeller marked this conversation as resolved.
Show resolved Hide resolved

8. Push the changes to your fork.
8. Push changes to your fork.
avivkeller marked this conversation as resolved.
Show resolved Hide resolved

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`).
* Allow maintainer access.
avivkeller marked this conversation as resolved.
Show resolved Hide resolved
* Reference the original PR in the description.
* Add `Backport-PR-URL:` metadata and re-push.
avivkeller marked this conversation as resolved.
Show resolved Hide resolved

10. Run [`node-test-pull-request`][] CI job (with default `REBASE_ONTO`).
avivkeller marked this conversation as resolved.
Show resolved Hide resolved

11. Replace `backport-requested-vN.x` with `backport-open-vN.x` on the original PR.
avivkeller marked this conversation as resolved.
Show resolved Hide resolved

12. Resolve conflicts with `git pull --rebase upstream vN.x-staging` if needed.
avivkeller marked this conversation as resolved.
Show resolved Hide resolved

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
Expand Down
Loading