backport-pr

Backport a merged Next.js pull request from canary to an LTS release branch (releases/lts/active or releases/lts/maintenance). Use when the user asks to backport, cherry-pick, or open a backport PR from a PR number to an older Next.js version. Covers finding the merged PR commit, creating a backport branch from the target release branch, cherry-picking from canary, validating, and opening the PR with the release branch as the base.

Backport PR

Use this skill when a user asks to backport a merged Next.js PR to a release branch.

Inputs

• Require a PR number and a target release branch. Almost always the target is one of the LTS branches: releases/lts/active (the current major's release line) or releases/lts/maintenance (the previous major's). Only in exceptionally rare circumstances — a fix for an older minor line that neither LTS branch supports anymore — is the target a non-LTS branch (next-<major>-<minor>, which any maintainer can create by pushing a branch from that line's last tag).
• If the target branch is not provided and cannot be inferred confidently from the user's request, ask before mutating git state — and default to an LTS branch unless the user explicitly names an old minor line.
• Treat the target branch as variable; do not hard-code a specific branch except when the user explicitly asks for it.

Workflow

1. Inspect the current worktree before changing branches:

   git status --short
   git branch --show-current
   

   Preserve unrelated user changes. Do not overwrite, reset, or stash them without the user's consent.

2. Sync the source and target branches:

   git fetch origin canary:refs/remotes/origin/canary <target-branch>:refs/remotes/origin/<target-branch>
   

3. Identify the commit that landed the PR on canary:

   gh pr view <pr-number> --repo vercel/next.js --json number,title,state,url,mergeCommit,baseRefName,headRefName
   git log origin/canary --oneline --fixed-strings --grep="(#<pr-number>)"
   

   Prefer mergeCommit.oid when the PR is MERGED and the commit is contained in origin/canary. If GitHub does not return a usable merge commit, use the git log --grep result and verify the commit subject references the PR number.

4. Create the backport branch from the release branch:

   git switch -c backport-<pr-number>-to-<target-branch> origin/<target-branch>
   

   After switching branches in this repo, run pnpm build-all before Next.js integration tests unless the user explicitly limits the task to preparing the cherry-pick or PR.

5. Cherry-pick the landed commit with provenance:

   git cherry-pick -x <merged-commit-sha>
   

   Resolve conflicts in favor of preserving the release branch's compatibility constraints. If the cherry-pick is empty, verify whether the change is already present on the release branch and report that instead of opening a duplicate PR.

6. Verify with the narrowest commands that cover the touched files. Prefer focused tests, pnpm types for TypeScript-only risk, and the relevant integration test mode for behavior changes.

7. Open the backport PR using $create-pr.

   Override the normal $create-pr base branch: use --base <target-branch>, not canary. Keep the PR as a draft unless the user explicitly asks otherwise.

PR Shape

The PR title should indicate the target branch and the original PR title.

Use a title like:

[lts-active] <original PR title>

or

[lts-maintenance] <original PR title>

Use a concise PR body:

Backports <original PR title/link> to `<target-branch>`.

<!-- NEXT_JS_LLM -->

Related Skills

• $create-pr - Create the branch commit, push it, and open the draft PR.
• $pr-status-triage - Check CI failures or review feedback after the PR exists.