Backporting to Release Lines

Learn how to backport pull requests to Node.js release lines using automated and manual processes.

Overview

Backporting allows important changes to be applied to previous Node.js release lines. This guide covers when and how to backport changes.

Staging Branches

Each release line has a staging branch for preparing releases:

vN.x-staging

Where N is the major release number (e.g., v20.x-staging, v22.x-staging).

For currently active staging branches, refer to the Release Schedule.

When Backporting is Needed

If a cherry-pick from main doesn’t apply cleanly to a staging branch, the pull request will be labeled with backport-requested-vN.x, indicating manual backporting is required.

Backporting Criteria

Current Release Line

The “Current” release line has more flexibility for backporting changes.

LTS Release Lines

Long-Term Support (LTS) branches have stricter requirements:

• Commits must mature in the Current release for at least two weeks before backporting
• Changes should be stable and well-tested
• Follow the Release Plan guidelines

LTS releases require commits to mature in Current for at least 2 weeks before backporting.

Backport Labels

Use these labels during the backport process (where N is the major version number):

Label	Description
backport-blocked-vN.x	PRs blocked by pending backports from other PRs
backport-open-vN.x	Indicates an open backport PR exists
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

Automated Backport Process

The automated process using Node.js core utilities is the recommended approach.

Prerequisites

Install the Node.js core utilities:

npm install -g @node-core/utils

Steps

# Backport PR #123 to v20.x-staging
git node backport 123 --to=20

After running this command, proceed to step 5 in the manual process below.

Manual Backport Process

Use this process when the automated method isn’t available or encounters issues.

Step 1: Checkout Staging Branch

# Fetch and checkout the staging branch
git fetch upstream vN.x-staging:vN.x-staging -f
git checkout -b backport-123-to-vN.x vN.x-staging

Step 2: Cherry-Pick Commits

# Cherry-pick the commit(s)
git cherry-pick <commit-hash>

You can cherry-pick multiple commits by listing their hashes separated by spaces.

Step 3: Resolve Conflicts

If conflicts occur:

# Edit conflicting files, then:
git add <resolved-files>
git cherry-pick --continue

Step 4: Preserve Commit Message

Leave the commit message as is. Don’t add Backport-PR-URL metadata yet - this will be done later.

If you think the commit message should be modified, comment in the pull request rather than changing it directly.

Step 5: Run Tests

Verify the backport works correctly:

make -j4 test

Step 6: Push to Your Fork

git push origin backport-123-to-vN.x

Step 7: Open Pull Request

Create a PR with:

Target: vN.x-staging

Title Format:

[vN.x backport] <commit title>

Example:

[v20.x backport] process: improve performance of nextTick

Description: Reference the original PR

Backport of #123

Original commit: <commit-hash>

Step 8: Update Labels

On the original pull request:

• Remove: backport-requested-vN.x
• Add: backport-open-vN.x

Step 9: Handle Rebase if Needed

If conflicts arise during review:

git pull --rebase upstream vN.x-staging
git push origin backport-123-to-vN.x --force-with-lease

Step 10: After Merge

Once the backport PR is merged, update the original PR:

• Remove: backport-open-vN.x
• Add: backported-to-vN.x

Common Scenarios

Backporting to Multiple Release Lines

If a change needs to be backported to multiple versions:

# Backport to v20.x
git node backport 123 --to=20

# Backport to v22.x
git node backport 123 --to=22

Create separate PRs for each release line.

Blocked Backports

If your backport depends on another PR that hasn’t been backported yet:

1. Add backport-blocked-vN.x label to your PR
2. Reference the blocking PR in a comment
3. Wait for the blocking PR to be backported first
4. Proceed with your backport after the dependency is resolved

Cherry-Picking Multiple Commits

For PRs with multiple commits:

# Cherry-pick commits in order
git cherry-pick <commit-1> <commit-2> <commit-3>

Or cherry-pick a range:

git cherry-pick <first-commit>^..<last-commit>

Best Practices

Test Thoroughly

# Run full test suite
make -j4 test

# Run specific subsystem tests
tools/test.py <subsystem>

Verify Compatibility

Ensure the backported change:

• Doesn’t introduce breaking changes
• Works with the older codebase
• Maintains API compatibility

Document Changes

If the backport required modifications:

• Document changes in the PR description
• Explain why modifications were necessary
• Note any differences from the original commit

Communication

• Keep the original PR author informed
• Tag relevant team members for review
• Mention any challenges encountered during backporting

Troubleshooting

Cherry-Pick Conflicts

# If cherry-pick fails, you can:

# 1. Abort and try a different approach
git cherry-pick --abort

# 2. Manually resolve conflicts
# Edit files, then:
git add <files>
git cherry-pick --continue

Failed Tests

If tests fail after backporting:

1. Review test failures carefully
2. Check if dependencies changed between versions
3. Adapt the backport as needed
4. Document any required modifications

Multiple Conflict Resolutions

For complex backports with many conflicts:

# Consider rebasing interactively
git rebase -i vN.x-staging

Release Process Integration

Backported changes follow this workflow:

1. Merged to staging: Change is in vN.x-staging
2. Release preparation: Staging branch is tested
3. Release: Change is included in the next vN.x release
4. Publication: Release is published to nodejs.org

Related Resources

Release Schedule

View active release lines

Release Plan

Understand release policies

Core Utils

Install backport automation tools

Git Node Backport

Backport command documentation

Quick Reference

# Automated backport (recommended)
git node backport <PR-number> --to=<version>

# Manual backport
git fetch upstream vN.x-staging:vN.x-staging -f
git checkout -b backport-<PR>-to-vN.x vN.x-staging
git cherry-pick <commit-hash>
make -j4 test
git push origin backport-<PR>-to-vN.x

# Create PR targeting vN.x-staging
# Title: [vN.x backport] <original-title>