Skip to main content

​
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):
LabelDescription
backport-blocked-vN.xPRs blocked by pending backports from other PRs
backport-open-vN.xIndicates an open backport PR exists
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

​
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

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>