Unverified Commit f2c2f781 authored by Jiwon Choi's avatar Jiwon Choi Committed by GitHub

Provide only the relevant context for agent upgrade (#99189)

Same-major security and latest updates received migration instructions
that could send agents through unnecessary codemods and Pages Router
work. Therefore split the docs and provide only the relevant context.
parent e1138ce5
...@@ -180,6 +180,11 @@ tail -5 /tmp/test-output.log # Summary ...@@ -180,6 +180,11 @@ tail -5 /tmp/test-output.log # Summary
- **Use `pnpm new-test` to generate new test suites** - it creates proper structure with fixture files - **Use `pnpm new-test` to generate new test suites** - it creates proper structure with fixture files
- **Normalize filesystem paths in cross-platform assertions.** Windows
`path.join()` uses backslashes. Normalize paths from mocked filesystem calls,
including `cp` sources and destinations, before positive or negative checks
that use `/`. Otherwise tests can fail on Windows or pass for the wrong reason.
- **Use `retry()` from `next-test-utils` instead of `setTimeout` for waiting** - **Use `retry()` from `next-test-utils` instead of `setTimeout` for waiting**
```typescript ```typescript
......
--- ---
title: Complete an agentic Next.js upgrade title: Complete an agentic Next.js major upgrade
description: Agent workflow for repository preflight, codemods, repairs, verification, and delivery of an agentic Next.js upgrade. description: Agent workflow for repository preflight, codemods, repairs, verification, and delivery across Next.js major versions.
# Experimental agent workflow. Not ready for indexing; keep this document marked as draft. # Experimental agent workflow. Not ready for indexing; keep this document marked as draft.
version: draft version: draft
--- ---
...@@ -19,44 +19,15 @@ dist-tag for stable installations and `canary` for canary installations. ...@@ -19,44 +19,15 @@ dist-tag for stable installations and `canary` for canary installations.
Security upgrades and advisory checks are supported only for stable installations. Security upgrades and advisory checks are supported only for stable installations.
Canary installations support `latest` and `future` without advisory assessment. Canary installations support `latest` and `future` without advisory assessment.
## 1. Check for duplicates ## 1. Make a checklist
Before reading another guide or changing files, complete every item: - [ ] Read `../codemods.md` and `../version-<major>.md` for each crossed major
from version 14 onward. Include each **Review migration checklist**.
- [ ] Identify the repository provider from `git remote -v`, then use its CLI or - [ ] For crossed majors through version 13, read the Pages Router guide under
API to list every open pull request. For GitHub, run `docs/02-pages/02-guides/upgrading/` and derive the checklist from it.
`gh pr list --state open --limit 100 --json number,title,body,url,headRefName`.
- [ ] Inspect the body and diff of likely matches. For GitHub, run
`gh pr diff <number>`.
- [ ] Check local and remote branches and commits for an equivalent upgrade.
Look for unmarked upgrades and these markers:
```md
<!-- next-upgrade: <type>; path="." -->
<!-- next-upgrade: <type>; path="apps/web" -->
```
Do not substitute Git history for the provider lookup. If any check is unavailable,
fails, or finds existing work, stop before changing files and report it. Continue
to step 2 only after every check completes and finds no equivalent work.
## 2. Make a checklist
If the Next.js version is unchanged, make the checklist from the Future Defaults
adoption references in the prompt instead of the version-migration guides below.
- [ ] Read `./codemods.md` and the applicable `./version-<major>.md` files for
every crossed major, or the target major for a same-major upgrade.
- [ ] For version 14 and later, include the **Review migration checklist**
section. For version 13 and below, derive the checklist from the Pages
Router guide under `docs/02-pages/02-guides/upgrading/`.
- [ ] Stop if a required guide is missing. - [ ] Stop if a required guide is missing.
## 3. Upgrade and repair ## 2. Upgrade and repair
If the Next.js version is unchanged, follow the Future Defaults adoption
references in the prompt instead of the codemod steps below.
- [ ] Run the exact command prepared for this upgrade: - [ ] Run the exact command prepared for this upgrade:
...@@ -75,34 +46,17 @@ references in the prompt instead of the codemod steps below. ...@@ -75,34 +46,17 @@ references in the prompt instead of the codemod steps below.
prompt, preserving unrelated configuration. If the target Next.js version prompt, preserving unrelated configuration. If the target Next.js version
does not support this option, skip the setting and report why. does not support this option, skip the setting and report why.
## 4. Verify ## 3. Verify
**This is the most important step.** **This is the most important step.**
- [ ] Review the checklist created in step 2 and verify that every item has been - [ ] Review the checklist created in step 1 and verify that every item has been
completed. Iterate until every item is addressed as applied or blocked completed. Iterate until every item is addressed as applied or blocked
with a reason. with a reason.
- [ ] Run the repository's checks, build when supported, and test affected - [ ] Run the repository's checks, build when supported, and test affected
runtime behavior. runtime behavior.
## 5. Commit and deliver ## Deliver
For adoption without a version change, group commits by the Future Default being
adopted instead of by crossed major.
- [ ] Commit the final diff in ascending major order, with one commit for each
crossed major. Each commit contains that major's surviving final-target
changes. Do not add transitional changes solely to make an intermediate
version work. Each commit message must include its source and target
versions and explain the change as if it were a PR description, so the
commit can later be split into its own PR.
- [ ] With permission, recheck open pull requests for duplicates and publish one
draft PR with the app marker:
```md
<!-- next-upgrade: <type>; path="." -->
<!-- next-upgrade: <type>; path="apps/web" -->
```
- [ ] If the upgrade is incomplete, report completed work, the blocker, and how - [ ] After verifying the migration and any requested Future Defaults adoption,
to resume. return to `shared.md` and complete its delivery checklist.
---
title: Adopt Next.js Future Defaults with an agent
description: Agent workflow for adopting Future Defaults after an optional Next.js version update.
# Experimental agent workflow. Not ready for indexing; keep this document marked as draft.
version: draft
---
Follow the Future Default adoption documents listed in the prompt. If the
installed and target Next.js versions differ, complete the version guide first.
## Adopt and verify
- [ ] Set `experimental.agenticAutoUpgrade` to the policy specified in the
prompt, preserving unrelated configuration. If the installed Next.js
version does not support this option, skip the setting and report why.
- [ ] Read and follow each adoption document in the prompt, in order. If none
are listed, continue to delivery. Complete each adoption; remove temporary
opt-outs and TODO markers after repair.
- [ ] Run the repository's checks, build when supported, and test affected
runtime behavior. Verify each adoption before moving to the next.
## Deliver
- [ ] After verifying the adoption, return to `shared.md` and complete its
delivery checklist.
---
title: Complete an agentic Next.js version update
description: Update Next.js within the same major version and verify the app.
# Experimental agent workflow. Not ready for indexing; keep this document marked as draft.
version: draft
---
Use the exact target version in the handoff prompt. Do not run a codemod or
follow a major-version migration guide for this same-major update.
## Install
- [ ] Install the exact target Next.js version. Update other dependencies if
needed for compatibility.
## Verify
- [ ] Confirm the installed version with `next --version`.
- [ ] Verify the app works with the updated dependencies and resolve any issues
caused by the update.
## Deliver
- [ ] After verifying the version update and any requested Future Defaults
adoption, return to `shared.md` and complete its delivery checklist.
---
title: Shared agentic Next.js upgrade checks and delivery
description: Duplicate checks and delivery for all agentic Next.js upgrade policies.
version: draft
---
## Before changing files: check for duplicates
- [ ] Identify the repository provider from `git remote -v`, then use its CLI or
API to list every open pull request. For GitHub, run
`gh pr list --state open --limit 100 --json number,title,body,url,headRefName`.
- [ ] Inspect the body and diff of likely matches. For GitHub, run
`gh pr diff <number>`.
- [ ] Check local and remote branches and commits for an equivalent upgrade or
Future Defaults adoption.
Look for unmarked work and these markers:
```md
<!-- next-upgrade: <type>; path="." -->
<!-- next-upgrade: <type>; path="apps/web" -->
```
Do not substitute Git history for the provider lookup. If any check is
unavailable, fails, or finds existing work, stop before changing files and
report it. Continue only when every check finds no equivalent work.
## After all upgrade and adoption steps: commit and deliver
- [ ] Commit the verified version update before Future Defaults adoption. For a
different-major update, use one commit for each crossed major, containing
that major's surviving final-target changes. Do not add transitional
changes solely to make an intermediate version work. Include source and
target versions in each commit message and explain why and how.
- [ ] Group Future Defaults changes by the default adopted. Explain why and how
in each commit message.
- [ ] With permission, recheck open pull requests for duplicates and publish one
draft PR with the app marker:
```md
<!-- next-upgrade: <type>; path="." -->
<!-- next-upgrade: <type>; path="apps/web" -->
```
- [ ] If permission to open a PR has not been granted, ask the user whether to
open one when reporting the completed work.
- [ ] If work is incomplete, report completed work, the blocker, and how to resume.
...@@ -2,7 +2,7 @@ import { spawn } from 'child_process' ...@@ -2,7 +2,7 @@ import { spawn } from 'child_process'
import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'fs/promises' import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'fs/promises'
import { tmpdir } from 'os' import { tmpdir } from 'os'
import { dirname, join } from 'path' import { dirname, join } from 'path'
import { prerelease, valid } from 'next/dist/compiled/semver' import { major, prerelease, valid } from 'next/dist/compiled/semver'
import * as Log from '../build/output/log' import * as Log from '../build/output/log'
import createSpinner from '../build/spinner' import createSpinner from '../build/spinner'
import { findDir } from '../lib/find-pages-dir' import { findDir } from '../lib/find-pages-dir'
...@@ -254,11 +254,13 @@ export async function spawnNextUpgrade( ...@@ -254,11 +254,13 @@ export async function spawnNextUpgrade(
return return
} }
const needsVersionMigration = const needsVersionUpdate =
result.installedVersion !== result.targetVersion result.installedVersion !== result.targetVersion
const crossesMajor =
major(result.installedVersion) !== major(result.targetVersion)
Log.info( Log.info(
needsVersionMigration needsVersionUpdate
? `Upgrade: Next.js ${result.installedVersion} → ${result.targetVersion}` ? `Upgrade: Next.js ${result.installedVersion} → ${result.targetVersion}`
: `Future Defaults: Next.js ${result.installedVersion}` : `Future Defaults: Next.js ${result.installedVersion}`
) )
...@@ -267,22 +269,94 @@ export async function spawnNextUpgrade( ...@@ -267,22 +269,94 @@ export async function spawnNextUpgrade(
// Retain them outside the app so dependency changes cannot remove them. // Retain them outside the app so dependency changes cannot remove them.
const bundledDocs = join(__dirname, '../docs') const bundledDocs = join(__dirname, '../docs')
const runDirectory = await mkdtemp(join(tmpdir(), 'next-upgrade-')) const runDirectory = await mkdtemp(join(tmpdir(), 'next-upgrade-'))
const guidePath = join( const guideName = crossesMajor
? 'different-major'
: needsVersionUpdate
? 'same-major'
: 'future-defaults'
const guideDirectory = 'docs/01-app/02-guides/upgrading/agentic-upgrade'
const sharedGuidePath = join(runDirectory, guideDirectory, 'shared.md')
const guidePath = join(runDirectory, guideDirectory, `${guideName}.md`)
const futureGuidePath = join(
runDirectory, runDirectory,
'docs/01-app/02-guides/upgrading/agentic-upgrade.md' guideDirectory,
'future-defaults.md'
) )
const guidesSpinner = createSpinner('Preparing upgrade') const guidesSpinner = createSpinner('Preparing upgrade')
try { try {
for (const router of ['01-app', '02-pages']) { await mkdir(dirname(guidePath), { recursive: true })
await cp(
join(
bundledDocs,
'01-app/02-guides/upgrading/agentic-upgrade/shared.md'
),
sharedGuidePath
)
await cp(
join(
bundledDocs,
'01-app/02-guides/upgrading/agentic-upgrade',
`${guideName}.md`
),
guidePath
)
if (crossesMajor) {
await cp( await cp(
join(bundledDocs, router, '02-guides/upgrading'), join(bundledDocs, '01-app/02-guides/upgrading/codemods.md'),
join(runDirectory, 'docs', router, '02-guides/upgrading'), join(runDirectory, 'docs/01-app/02-guides/upgrading/codemods.md')
{ recursive: true } )
for (
let version = major(result.installedVersion) + 1;
version <= major(result.targetVersion);
version++
) {
const router = version < 14 ? '02-pages' : '01-app'
const destination = join(
runDirectory,
'docs',
router,
'02-guides/upgrading',
`version-${version}.md`
)
await mkdir(dirname(destination), { recursive: true })
await cp(
join(
bundledDocs,
router,
'02-guides/upgrading',
`version-${version}.md`
),
destination
)
}
if (major(result.installedVersion) < 13) {
await mkdir(
join(runDirectory, 'docs/02-pages/02-guides/upgrading'),
{ recursive: true }
)
await cp(
join(bundledDocs, '02-pages/02-guides/upgrading/codemods.md'),
join(
runDirectory,
'docs/02-pages/02-guides/upgrading/codemods.md'
)
)
}
}
if (upgradeType === 'future' && needsVersionUpdate) {
await cp(
join(
bundledDocs,
'01-app/02-guides/upgrading/agentic-upgrade/future-defaults.md'
),
futureGuidePath
) )
} }
if (needsVersionMigration) { if (crossesMajor) {
const codemodVersion = process.env.__NEXT_VERSION const codemodVersion = process.env.__NEXT_VERSION
if (!codemodVersion) { if (!codemodVersion) {
throw new Error('Could not determine the @next/codemod version.') throw new Error('Could not determine the @next/codemod version.')
...@@ -359,24 +433,23 @@ export async function spawnNextUpgrade( ...@@ -359,24 +433,23 @@ export async function spawnNextUpgrade(
? 'the installed version is affected by a published security advisory' ? 'the installed version is affected by a published security advisory'
: upgradeType === 'latest' : upgradeType === 'latest'
? `a newer ${releaseKind} Next.js release is available` ? `a newer ${releaseKind} Next.js release is available`
: `the Future policy applies the latest ${releaseKind} release and adopts its Future Defaults` : `the Future policy applies the latest ${releaseKind} release${preparedFutureDefaults.length > 0 ? ' and adopts its Future Defaults' : ''}`
const futureDefaultsPrompt = preparedFutureDefaults.length const futureDefaultsList = preparedFutureDefaults
? ` .map(
${needsVersionMigration ? 'After completing and verifying the version migration, adopt' : 'Adopt'} these Future Defaults in order: (futureDefault) =>
${preparedFutureDefaults `- ${futureDefault.name}\n${futureDefault.documents.map((document) => ` - Read and follow ${JSON.stringify(document)}.`).join('\n')}`
.map( )
(futureDefault) => .join('\n')
`- ${futureDefault.name}\n${futureDefault.documents.map((document) => ` - Read and follow ${JSON.stringify(document)}.`).join('\n')}` const futureDefaultsPrompt =
) upgradeType === 'future'
.join('\n')} ? `${needsVersionUpdate ? `After completing and verifying the version update, read and follow ${JSON.stringify(futureGuidePath)}.\n` : ''}${futureDefaultsList ? `Adopt these Future Defaults in order:\n${futureDefaultsList}\nComplete each adoption. Temporary opt-outs and TODO markers are intermediate work only; do not stop until they are removed and the adoption is fully verified.` : 'No Future Defaults are pending adoption.'}`
Complete each adoption. Temporary opt-outs and TODO markers are intermediate work only; do not stop until they are removed and the adoption is fully verified.` : ''
: ''
// Pass resolved inputs directly; the agent owns repairs and verification. // Pass resolved inputs directly; the agent owns repairs and verification.
const taskSummary = needsVersionMigration const taskSummary = needsVersionUpdate
? `We're upgrading the app in ${JSON.stringify(baseDir)} from Next.js ${result.installedVersion} to ${result.targetVersion} because ${reason}.` ? `We're upgrading the app in ${JSON.stringify(baseDir)} from Next.js ${result.installedVersion} to ${result.targetVersion} because ${reason}.`
: `We're adopting the Future Defaults available to the app in ${JSON.stringify(baseDir)}, which already uses Next.js ${result.installedVersion}.` : `We're adopting the Future Defaults available to the app in ${JSON.stringify(baseDir)}, which already uses Next.js ${result.installedVersion}.`
const prompt = `Read and follow every applicable instruction in ${JSON.stringify(guidePath)} before proceeding. const prompt = `Read and follow ${JSON.stringify(sharedGuidePath)} first. Complete its duplicate checks before changing files. Then read and follow every applicable instruction in ${JSON.stringify(guidePath)}.
${taskSummary} ${taskSummary}
......
This diff is collapsed.
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