Skip to main content

How to backport a pull request to a release line

Staging branches​

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 active staging branches, refer to the Release Schedule.

Identifying changes that require a backport​

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.

Criteria for backporting​

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.

Labeling backport issues and PRs​

Use the following labels, with N in vN.x denoting the major release number:

LabelDescription
backport-blocked-vN.xPRs for vN.x-staging blocked by pending backports from other PRs.
backport-open-vN.xIndicates an open backport for the PR.
backport-requested-vN.xPR awaiting manual backport to vN.x-staging.
backported-to-vN.xPR successfully backported to vN.x-staging.
baking-for-ltsPRs awaiting LTS release after maturation in Current.
lts-watch-vN.xPRs possibly included in vN.x LTS releases.
vN.xIssues or PRs impacting vN.x-staging (or reproducible on vN.x).

Submitting a backport pull request​

For the following steps, let's assume that you need to backport PR 123 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 N with the version number for the targeted release line.

Automated process​

  1. Ensure @node-core/utils is installed.

  2. Execute git node backport command:

    # Example: Backport PR 123 to vN.x-staging
    git node backport 123 --to=N

  3. Proceed to step 5 in the Manual section below.

Manual process​

  1. Checkout the vN.x-staging branch.

  2. Verify that the local staging branch is up to date with the remote.

  3. Create a new branch based on vN.x-staging:

    git fetch upstream vN.x-staging:vN.x-staging -f
    git checkout -b backport-123-to-vN.x vN.x-staging

  4. Cherry-pick the desired commit(s):

    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 in the pull request. The Backport-PR-URL metadata does need to be added to the commit, but this will be done later.

  7. Verify that make -j4 test passes.

  8. Push the changes to your fork.

  9. Open a pull request:

    • 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:

    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.