Unverified Commit 03d5842d authored by Sebastian "Sebbie" Silbermann's avatar Sebastian "Sebbie" Silbermann Committed by GitHub

[cd] Replace versioned release branches with fixed `releases/lts/*` refs (#99807)

Release branches no longer carry the version number. Two long-lived,
manually-created branches replace them: `releases/lts/active` (current
major's release line) and `releases/lts/maintenance` (previous major's).

From then on, triggering a stable release moves the refs automatically,
via the release GitHub App (next.js bot) credentials already used for
the signed release commit:

- **patch**: no ref moves — the release commit already advances the
branch it was cut on
- **minor**: routed by the released version's major against the latest
major (the one `releases/lts/active` currently points at) — equal moves
`releases/lts/active` to the new tag, latest − 1 moves
`releases/lts/maintenance` to the new tag, anything else moves nothing
- **major**: `releases/lts/maintenance` takes `releases/lts/active`'s
previous position, then `releases/lts/active` moves to the new tag

Supporting changes:

- `scripts/release-branches.json` lists the fixed branch set (`canary` +
both LTS branches) so `version-bump.js` allows bumps on them
- `build_and_test.yml` / `build_and_deploy.yml` run on pushes to the LTS
branches, and the staging deploy-target condition covers them (parity
with the per-branch rewrite the removed script used to produce)
- `backport-pr` skill, `AGENTS.md`, `release-channels-publishing.md`,
and a stale `version-bump.js` comment updated for the new branch model
Co-authored-by: 's avatarClaude Code <noreply@anthropic.com>
parent 76bed42c
---
name: backport-pr
description: >
Backport a merged Next.js pull request from canary to a previous release
branch such as next-16-2. 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 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.
metadata:
internal: true
---
......@@ -18,11 +18,14 @@ branch.
## Inputs
- Require a PR number and a target release branch, for example `next-16-2`.
- Require a PR number and a target release branch:
`releases/lts/active` (the current major's release line) or
`releases/lts/maintenance` (the previous major's), depending on which
released line needs the fix.
- If the target branch is not provided and cannot be inferred confidently from
the user's request, ask before mutating git state.
- Treat the target branch as variable; do not hard-code `next-16-2` except when
the user explicitly asks for it.
- Treat the target branch as variable; do not hard-code either LTS branch
except when the user explicitly asks for it.
## Workflow
......
......@@ -3,7 +3,7 @@ name: build-and-deploy
on:
push:
branches: ['canary']
branches: ['canary', 'releases/lts/active', 'releases/lts/maintenance']
# Run on release tags so publishing is driven by the tag push rather than
# the release-commit branch push (see the deploy-target step).
tags:
......@@ -68,8 +68,8 @@ jobs:
corepack enable
- name: Determine deploy target
# 'force-preview' performs a full preview build but only if acknowledged i.e. workflow_dispatch
# 'automated-preview' for pushes on branches other than 'canary' for integration testing.
# 'staging' for canary branch since that will eventually be published i.e. become the production build.
# 'automated-preview' for pushes on branches other than the publishable ones for integration testing.
# 'staging' for canary and the LTS branches since those will eventually be published i.e. become the production build.
id: deploy-target
run: |
RELEASE_VERSION="$(node ./scripts/check-is-release.js 2> /dev/null || :)"
......@@ -108,7 +108,9 @@ jobs:
fi
echo "release_environment=$RELEASE_ENVIRONMENT" >> $GITHUB_OUTPUT
fi
elif [ ''"${GIT_REF}"'' == 'refs/heads/canary' ]
elif [[ ''"${GIT_REF}"'' == 'refs/heads/canary' ||
''"${GIT_REF}"'' == 'refs/heads/releases/lts/active' ||
''"${GIT_REF}"'' == 'refs/heads/releases/lts/maintenance' ]]
then
echo "value=staging" >> $GITHUB_OUTPUT
elif [ '${{ github.event_name }}' == 'workflow_dispatch' ]
......
......@@ -2,7 +2,7 @@ name: build-and-test
on:
push:
branches: ['canary']
branches: ['canary', 'releases/lts/active', 'releases/lts/maintenance']
pull_request:
types: [opened, synchronize]
......
on:
workflow_dispatch:
inputs:
branchName:
description: name of branch to create (next-15-4)
required: true
type: string
tagName:
description: Tag to start the branch from (v15.4.1)
type: string
required: true
name: Create Release Branch
env:
NAPI_CLI_VERSION: 3.7.2
TURBO_VERSION: 2.9.4
NODE_LTS_VERSION: 20
jobs:
start:
if: github.repository_owner == 'vercel'
runs-on: ubuntu-latest
env:
NEXT_TELEMETRY_DISABLED: 1
steps:
- name: Setup node
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version: ${{ env.NODE_LTS_VERSION }}
check-latest: true
package-manager-cache: false
- name: Create GitHub App token
id: release-app-token
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
with:
client-id: ${{ vars.RELEASE_GITHUB_APP_CLIENT_ID }}
private-key: ${{ secrets.RELEASE_GITHUB_APP_PRIVATE_KEY }}
owner: ${{ github.repository_owner }}
repositories: next.js
permission-contents: write
permission-workflows: write
- name: Get GitHub App user ID
id: release-app-user
run: |
user_id="$(gh api "/users/${{ steps.release-app-token.outputs.app-slug }}[bot]" --jq .id)"
echo "user-id=$user_id" >> "$GITHUB_OUTPUT"
env:
GH_TOKEN: ${{ steps.release-app-token.outputs.token }}
- name: Clone Next.js repository
run: git clone https://github.com/vercel/next.js.git --depth=25 --single-branch --branch ${GITHUB_REF_NAME:-canary} .
- name: Check token
run: gh auth status
env:
GH_TOKEN: ${{ steps.release-app-token.outputs.token }}
# https://github.com/actions/virtual-environments/issues/1187
- name: tune linux network
run: sudo ethtool -K eth0 tx off rx off
- name: Setup corepack
run: |
npm i -g corepack@0.31
corepack enable
pnpm --version
- id: get-store-path
run: echo STORE_PATH=$(pnpm store path) >> $GITHUB_OUTPUT
- uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
timeout-minutes: 5
id: cache-pnpm-store
with:
path: ${{ steps.get-store-path.outputs.STORE_PATH }}
key: pnpm-store-root-v1-${{ hashFiles('pnpm-lock.yaml') }}
# Do not use restore-keys since it leads to indefinite growth of the cache.
- run: pnpm install
- run: node ./scripts/create-release-branch.js --branch-name "${INPUT_BRANCHNAME}" --tag-name "${INPUT_TAGNAME}"
env:
RELEASE_GITHUB_TOKEN: ${{ steps.release-app-token.outputs.token }}
RELEASE_GITHUB_APP_SLUG: ${{ steps.release-app-token.outputs.app-slug }}
RELEASE_GITHUB_APP_USER_ID: ${{ steps.release-app-user.outputs.user-id }}
INPUT_BRANCHNAME: ${{ github.event.inputs.branchName }}
INPUT_TAGNAME: ${{ github.event.inputs.tagName }}
......@@ -398,7 +398,7 @@ Use skills for conditional, deep workflows. Keep baseline iteration/build/test p
- `$pr-status-triage` - CI failure and PR review triage with `scripts/pr-status.js`
- `$create-pr` - branch, commit, push, and draft PR creation workflow
- `$deploy-release-test` - validate a commit preview package and trigger the full `test_e2e_deploy_release.yml` suite
- `$backport-pr` - cherry-pick merged PRs from `canary` to release branches
- `$backport-pr` - cherry-pick merged PRs from `canary` to `releases/lts/active` or `releases/lts/maintenance`
- `$flags` - feature-flag wiring across config/schema/define-env/runtime env
- `$dce-edge` - DCE-safe `require()` patterns and edge/runtime constraints
- `$react-vendoring` - `entry-base.ts` boundaries and vendored React type/runtime rules
......
......@@ -37,5 +37,15 @@ which builds the packages and publishes them to npm under the dist-tag matching
the channel.
Version bumps are restricted to the release branches listed in
`scripts/release-branches.json`. `scripts/create-release-branch.js` adds a new
release branch to that list when one is created.
`scripts/release-branches.json`: `canary` and the two long-lived LTS branches
`releases/lts/active` (the current major's release line) and
`releases/lts/maintenance` (the previous major's). The LTS branches are created
manually, once, and from then on a stable release moves the refs automatically:
- `patch`: no ref moves — the release commit already advances the branch it was
cut on.
- `minor`: the new tag is routed by its major against the latest published
major (the npm `latest` dist-tag) — equal moves `releases/lts/active` to the
tag; latest − 1 moves `releases/lts/maintenance` to the tag.
- `major`: `releases/lts/maintenance` is moved to where `releases/lts/active`
pointed, and `releases/lts/active` is moved to the new tag.
// @ts-check
const fs = require('fs')
const path = require('path')
const execa = require('execa')
const {
configureGitHubAuth,
getGitHubToken,
getGitHubTokenMissingMessage,
} = require('./release-github-auth')
const {
githubRequest,
createSignedCommit,
upsertBranchRef,
} = require('./github-utils/signed-commit')
const REPO_OWNER = 'vercel'
const REPO_NAME = 'next.js'
/**
* Fail fast, before any file mutation, if the branch already exists.
*
* This doubles as the API preflight: it exercises the same git-data path the
* script later writes to (blobs/trees/commits/refs), so a token missing those
* grants fails here rather than midway through creating objects. A plain
* repository GET would succeed with any valid installation token and so could
* never catch that.
*/
async function verifyBranchIsAvailable(token, branch) {
let existing
try {
existing = await githubRequest(
token,
'GET',
`/repos/${REPO_OWNER}/${REPO_NAME}/git/ref/heads/${branch}`
)
} catch (error) {
const message = error instanceof Error ? error.message : String(error)
// A 404 is the expected, successful outcome: the branch is available.
if (message.includes('failed (404)')) {
console.log(`Verified GitHub API access; branch ${branch} is available`)
return
}
throw error
}
throw new Error(
`Branch ${branch} already exists (at ${existing.object?.sha}). ` +
`Delete it or choose a different branch name before re-running.`
)
}
async function main() {
const args = process.argv
const branchName = args[args.indexOf('--branch-name') + 1]
const tagName = args[args.indexOf('--tag-name') + 1]
if (!branchName) {
throw new Error('branchName value is missing!')
}
if (!tagName || !tagName.startsWith('v')) {
throw new Error('tagName value is invalid "' + tagName + '"')
}
const githubToken = getGitHubToken()
if (!githubToken) {
console.log(getGitHubTokenMissingMessage())
return
}
await configureGitHubAuth(githubToken)
await verifyBranchIsAvailable(githubToken, branchName)
await execa('git', ['checkout', '-b', branchName], {
stdio: 'inherit',
})
await execa('git', ['fetch', 'origin', tagName, '--tags'], {
stdio: 'inherit',
})
await execa('git', ['reset', '--hard', tagName], {
stdio: 'inherit',
})
// Release branches need to be added here or `scripts/version-bump.js`
// refuses to run on them.
const releaseBranchesPath = path.join(__dirname, 'release-branches.json')
const releaseBranches = JSON.parse(
await fs.promises.readFile(releaseBranchesPath, 'utf8')
)
releaseBranches.push(branchName)
await fs.promises.writeFile(
releaseBranchesPath,
JSON.stringify(releaseBranches, null, 2) + '\n'
)
const buildAndDeployPath = path.join(
__dirname,
'..',
'.github',
'workflows',
'build_and_deploy.yml'
)
const buildAndDeploy = await fs.promises.readFile(buildAndDeployPath, 'utf8')
await fs.promises.writeFile(
buildAndDeployPath,
buildAndDeploy
// The push trigger is limited to the default branch, same as
// build_and_test.yml below, so point it at the release branch as well.
.replace(`branches: ['canary']`, `branches: ['${branchName}']`)
.replace(/refs\/heads\/canary/g, `refs/heads/${branchName}`)
)
const buildAndTestPath = path.join(
__dirname,
'..',
'.github',
'workflows',
'build_and_test.yml'
)
let buildAndTest = await fs.promises.readFile(buildAndTestPath, 'utf8')
buildAndTest = buildAndTest
.replace(`['canary']`, `['${branchName}']`)
.replace(/[\s]{1,}('test-new-tests-.+',)/g, '')
await fs.promises.writeFile(buildAndTestPath, buildAndTest)
const commitMessage = 'setup release branch'
await execa('git', ['add', '.'], {
stdio: 'inherit',
})
await execa('git', ['commit', '-m', commitMessage], {
stdio: 'inherit',
})
// Branch protection requires signed commits, so create the commit on the
// remote as a GitHub-signed commit via the REST API instead of running
// `git push` (which would push the unsigned local commit).
//
// Release tags are annotated tag objects, so dereference to the underlying
// commit -- the tag object's SHA is not valid as a commit parent.
const { stdout: baseSha } = await execa('git', [
'rev-parse',
`${tagName}^{commit}`,
])
const { stdout: localCommitSha } = await execa('git', ['rev-parse', 'HEAD'])
const signedCommit = await createSignedCommit({
token: githubToken,
owner: REPO_OWNER,
repo: REPO_NAME,
baseSha: baseSha.trim(),
localCommitSha: localCommitSha.trim(),
message: commitMessage,
})
await upsertBranchRef({
token: githubToken,
owner: REPO_OWNER,
repo: REPO_NAME,
branch: branchName,
sha: signedCommit.sha,
})
console.log(
`Created branch ${branchName} at signed commit ${signedCommit.sha}`
)
}
main()
["canary"]
["canary", "releases/lts/active", "releases/lts/maintenance"]
......@@ -12,6 +12,9 @@ const { readReleaseVersion } = require('./release-version')
const REPO_API_PATH = '/repos/vercel/next.js'
const LTS_ACTIVE_BRANCH = 'releases/lts/active'
const LTS_MAINTENANCE_BRANCH = 'releases/lts/maintenance'
async function git(args, options = {}) {
const { captureOutput = false, ...execaOptions } = options
const { stdout } = await execa('git', args, {
......@@ -188,6 +191,128 @@ async function createGitHubReleaseCommit(token, options = {}) {
}
}
/**
* Current commit SHA of a branch ref. Fails loudly (the API error propagates)
* when the branch does not exist — the LTS branches are bootstrapped manually,
* so a missing ref is an operator error, not something to paper over.
*/
async function getBranchSha(request, token, branch) {
const ref = await request(
token,
'GET',
`${REPO_API_PATH}/git/ref/heads/${branch}`
)
return ref.object.sha
}
/**
* The latest published stable major, read from npm (equivalent to
* `npm view next version`; the same dist-tags endpoint computePreviewVersion
* in start-release.js uses). Older majors publish under the `backport`
* dist-tag, so `latest` always tracks the newest release line.
*/
async function getLatestPublishedMajor() {
const res = await fetch('https://registry.npmjs.org/-/package/next/dist-tags')
const tags = await res.json()
if (!tags.latest) {
throw new Error('Failed to read the latest dist-tag of next from npm')
}
return semver.major(tags.latest)
}
/**
* Move the long-lived LTS branch refs after a stable release:
* - patch: nothing (the release commit already advanced the branch it was cut
* on)
* - minor: routed by the released version's major against the latest
* published major (npm `latest`): equal moves `releases/lts/active` to the
* new tag, latest - 1 moves `releases/lts/maintenance` to the new tag,
* anything else moves nothing
* - major: `releases/lts/maintenance` is moved to active's previous position,
* then `releases/lts/active` is moved to the new tag
*
* All PATCHes use `force: true` because the histories diverge (e.g. the tag
* commit for a major cut on canary is not a descendant of active's tip). When
* the release was cut on the LTS branch itself, `createGitHubReleaseCommit`
* already moved that branch to the same commit, so the move is a no-op.
*
* On partial failure (maintenance moved, active move failed) no rollback is
* attempted: every target commit already exists on the remote, nothing
* dangles, and the thrown error states the intended end state for manual
* repair.
*
* @param {string} token GitHub API token with repo access
* @param {object} options
* @param {'patch' | 'minor' | 'major'} options.semverType
* @param {string} options.tagName The just-created release tag (e.g. v16.3.0)
* @param {string} options.tagSha The signed commit the tag points at
* @param {import('./github-utils/signed-commit').githubRequest} [options.githubRequest]
* A custom GitHub client e.g. for using a logging mock when doing a dry run.
*/
async function updateLtsBranchRefs(
token,
{ semverType, tagName, tagSha, githubRequest: request = githubRequest }
) {
if (semverType === 'patch') {
console.log('Stable patch release: LTS branch refs unchanged')
return
}
if (semverType === 'major') {
const activeSha = await getBranchSha(request, token, LTS_ACTIVE_BRANCH)
await request(
token,
'PATCH',
`${REPO_API_PATH}/git/refs/heads/${LTS_MAINTENANCE_BRANCH}`,
{ sha: activeSha, force: true }
)
console.log(
`Moved ${LTS_MAINTENANCE_BRANCH} to ${activeSha} (previous ${LTS_ACTIVE_BRANCH} tip)`
)
await request(
token,
'PATCH',
`${REPO_API_PATH}/git/refs/heads/${LTS_ACTIVE_BRANCH}`,
{ sha: tagSha, force: true }
)
console.log(`Moved ${LTS_ACTIVE_BRANCH} to ${tagName} (${tagSha})`)
return
}
// The local HEAD is the just-created release commit, so the version source
// of truth carries the released version (same assumption
// `getLocalReleaseTagName` makes).
const newMajor = semver.major(readReleaseVersion())
const latestMajor = await getLatestPublishedMajor()
if (newMajor === latestMajor) {
await request(
token,
'PATCH',
`${REPO_API_PATH}/git/refs/heads/${LTS_ACTIVE_BRANCH}`,
{ sha: tagSha, force: true }
)
console.log(`Moved ${LTS_ACTIVE_BRANCH} to ${tagName} (${tagSha})`)
} else if (newMajor === latestMajor - 1) {
await request(
token,
'PATCH',
`${REPO_API_PATH}/git/refs/heads/${LTS_MAINTENANCE_BRANCH}`,
{ sha: tagSha, force: true }
)
console.log(`Moved ${LTS_MAINTENANCE_BRANCH} to ${tagName} (${tagSha})`)
} else {
console.log(
`${tagName} (major ${newMajor}) is on neither the active (major ${latestMajor}) ` +
`nor the maintenance (major ${latestMajor - 1}) line: LTS branch refs unchanged`
)
}
}
/**
* Find the previous release tag for a changelog range: the highest-semver tag
* reachable from `tagCommitSha` whose version is below `newVersion`. Returns
......@@ -286,4 +411,5 @@ async function createGitHubRelease(
module.exports = {
createGitHubReleaseCommit,
createGitHubRelease,
updateLtsBranchRefs,
}
......@@ -10,6 +10,7 @@ const {
const {
createGitHubReleaseCommit,
createGitHubRelease,
updateLtsBranchRefs,
} = require('./release-github-api')
const { readReleaseVersion } = require('./release-version')
......@@ -39,6 +40,11 @@ function createMockGitHubRequest() {
}`
)
// Branch ref lookups (LTS branch moves): a canned commit SHA.
if (method === 'GET' && apiPath.includes('/git/ref/heads/')) {
return { object: { sha: 'f'.repeat(40), type: 'commit' } }
}
// One canned shape covers every consumer: `.sha` (blobs/trees/commits) and
// `.verification.verified` (commits). Ref writes ignore the return value.
return {
......@@ -239,10 +245,23 @@ async function main() {
)
}
const { tagName } = await createGitHubReleaseCommit(githubToken, {
...releaseCommitOptions,
githubRequest: mockRequest,
})
const { tagName, sha: signedTagSha } = await createGitHubReleaseCommit(
githubToken,
{
...releaseCommitOptions,
githubRequest: mockRequest,
}
)
if (releaseType === 'stable') {
await updateLtsBranchRefs(githubToken, {
// Validated against SEMVER_TYPES above (stable always requires one).
semverType: /** @type {'patch' | 'minor' | 'major'} */ (semverType),
tagName,
tagSha: signedTagSha,
githubRequest: mockRequest,
})
}
if (isCanary || isReleaseCandidate || isBeta || isPreview) {
await createGitHubRelease(githubToken, {
......
......@@ -90,8 +90,9 @@ function parseArgs(argv) {
}
/**
* Releases are restricted to `canary` and the release branches.
* `scripts/create-release-branch.js` adds new release branches to the list.
* Releases are restricted to `canary` and the long-lived LTS release branches
* (`releases/lts/active`, `releases/lts/maintenance`) listed in
* `scripts/release-branches.json`.
*
* @param {string[]} allowBranchOverride
*/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment