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

Move upgrade workflows out of public docs (#99546)

Stacked on #99545.

### Why?

The draft agent upgrade workflows are internal instructions, but
currently ship alongside public documentation. Keep them beside the
upgrade implementation and outside the public docs bundle.

### How?

Move the four workflows to `src/lib/upgrade/*.md` and copy them to
`dist/lib/upgrade` with Taskr. Update `next upgrade` to prepare them
under the temporary `upgrade/` directory, including their guide
references and prompt assertions. Public migration guides remain in
`dist/docs`.

Verified the Taskr copy output. Full local build, lint, and unit-test
verification remain unavailable because workspace dependencies are
missing.
parent 4e0e573a
...@@ -396,13 +396,14 @@ export async function spawnNextUpgrade( ...@@ -396,13 +396,14 @@ 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.
failureStage = 'guide' failureStage = 'guide'
const bundledDocs = join(__dirname, '../docs') const bundledDocs = join(__dirname, '../docs')
const bundledGuides = join(__dirname, '../lib/upgrade')
const runDirectory = await mkdtemp(join(tmpdir(), 'next-upgrade-')) const runDirectory = await mkdtemp(join(tmpdir(), 'next-upgrade-'))
const guideName = crossesMajor const guideName = crossesMajor
? 'different-major' ? 'different-major'
: needsVersionUpdate : needsVersionUpdate
? 'same-major' ? 'same-major'
: 'future-defaults' : 'future-defaults'
const guideDirectory = 'docs/01-app/02-guides/upgrading/agentic-upgrade' const guideDirectory = 'upgrade'
const sharedGuidePath = join(runDirectory, guideDirectory, 'shared.md') const sharedGuidePath = join(runDirectory, guideDirectory, 'shared.md')
const guidePath = join(runDirectory, guideDirectory, `${guideName}.md`) const guidePath = join(runDirectory, guideDirectory, `${guideName}.md`)
const futureGuidePath = join( const futureGuidePath = join(
...@@ -414,23 +415,13 @@ export async function spawnNextUpgrade( ...@@ -414,23 +415,13 @@ export async function spawnNextUpgrade(
try { try {
await mkdir(dirname(guidePath), { recursive: true }) await mkdir(dirname(guidePath), { recursive: true })
await cp( await cp(join(bundledGuides, 'shared.md'), sharedGuidePath)
join( await cp(join(bundledGuides, `${guideName}.md`), guidePath)
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) { if (crossesMajor) {
await mkdir(join(runDirectory, 'docs/01-app/02-guides/upgrading'), {
recursive: true,
})
await cp( await cp(
join(bundledDocs, '01-app/02-guides/upgrading/codemods.md'), join(bundledDocs, '01-app/02-guides/upgrading/codemods.md'),
join(runDirectory, 'docs/01-app/02-guides/upgrading/codemods.md') join(runDirectory, 'docs/01-app/02-guides/upgrading/codemods.md')
...@@ -475,13 +466,7 @@ export async function spawnNextUpgrade( ...@@ -475,13 +466,7 @@ export async function spawnNextUpgrade(
} }
if (upgradeType === 'experimental-future' && needsVersionUpdate) { if (upgradeType === 'experimental-future' && needsVersionUpdate) {
await cp( await cp(join(bundledGuides, 'future-defaults.md'), futureGuidePath)
join(
bundledDocs,
'01-app/02-guides/upgrading/agentic-upgrade/future-defaults.md'
),
futureGuidePath
)
} }
if (crossesMajor) { if (crossesMajor) {
......
---
title: Complete an agentic Next.js major 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.
version: draft
---
Each section has a checklist of items to complete. Read line by line and complete Each section has a checklist of items to complete. Read line by line and complete
each item before moving on to the next section. each item before moving on to the next section.
...@@ -22,10 +15,11 @@ Canary installations support `latest` and `experimental-future` without advisory ...@@ -22,10 +15,11 @@ Canary installations support `latest` and `experimental-future` without advisory
## 1. Make a checklist ## 1. Make a checklist
- [ ] Read `../codemods.md` and `../version-<major>.md` for each crossed major - [ ] Read `../docs/01-app/02-guides/upgrading/codemods.md` and
`../docs/01-app/02-guides/upgrading/version-<major>.md` for each crossed major
from version 14 onward. Include each **Review migration checklist**. from version 14 onward. Include each **Review migration checklist**.
- [ ] For crossed majors through version 13, read the Pages Router guide under - [ ] For crossed majors through version 13, read the Pages Router guide under
`docs/02-pages/02-guides/upgrading/` and derive the checklist from it. `../docs/02-pages/02-guides/upgrading/` and derive the checklist from it.
- [ ] Stop if a required guide is missing. - [ ] Stop if a required guide is missing.
## 2. Upgrade and repair ## 2. Upgrade and repair
......
---
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 Follow the Future Default adoption documents listed in the prompt. If the
installed and target Next.js versions differ, complete the version guide first. installed and target Next.js versions differ, complete the version guide first.
......
---
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 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. follow a major-version migration guide for this same-major update.
......
---
title: Shared agentic Next.js upgrade checks and delivery
description: Duplicate checks, verification, and delivery for all agentic Next.js upgrade policies.
version: draft
---
## Before changing files: check for duplicates ## Before changing files: check for duplicates
- [ ] Check the app for an equivalent upgrade or Future Defaults adoption already - [ ] Check the app for an equivalent upgrade or Future Defaults adoption already
......
...@@ -50,6 +50,11 @@ export async function copy_docs(task, opts) { ...@@ -50,6 +50,11 @@ export async function copy_docs(task, opts) {
await task await task
.source(join(__dirname, 'src/agent-feedback/protocol.md')) .source(join(__dirname, 'src/agent-feedback/protocol.md'))
.target('dist/agent-feedback') .target('dist/agent-feedback')
// Keep upgrade workflow instructions outside the public docs bundle.
await task
.source(join(__dirname, 'src/lib/upgrade/*.md'))
.target('dist/lib/upgrade')
} }
export async function copy_styled_jsx_assets(task, opts) { export async function copy_styled_jsx_assets(task, opts) {
......
...@@ -1239,7 +1239,7 @@ describe('agentic upgrade prompts', () => { ...@@ -1239,7 +1239,7 @@ describe('agentic upgrade prompts', () => {
expect(prepareUpgrade).toHaveBeenCalledWith('/workspace/app', 'security') expect(prepareUpgrade).toHaveBeenCalledWith('/workspace/app', 'security')
const [guidePath, guide] = jest.mocked(writeFile).mock.calls[0] const [guidePath, guide] = jest.mocked(writeFile).mock.calls[0]
expect(String(guidePath).replace(/\\+/g, '/')).toBe( expect(String(guidePath).replace(/\\+/g, '/')).toBe(
'/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/different-major.md' '/tmp/next-upgrade-test/upgrade/different-major.md'
) )
expect(String(guide)).toMatch( expect(String(guide)).toMatch(
/^Run npx @next\/codemod@\S+ upgrade 16\.3\.5 --yes --skip-adoption$/ /^Run npx @next\/codemod@\S+ upgrade 16\.3\.5 --yes --skip-adoption$/
...@@ -1247,8 +1247,8 @@ describe('agentic upgrade prompts', () => { ...@@ -1247,8 +1247,8 @@ describe('agentic upgrade prompts', () => {
const copiedSources = normalizedCopiedSources() const copiedSources = normalizedCopiedSources()
expect(copiedSources).toEqual( expect(copiedSources).toEqual(
expect.arrayContaining([ expect.arrayContaining([
expect.stringContaining('/agentic-upgrade/shared.md'), expect.stringContaining('/lib/upgrade/shared.md'),
expect.stringContaining('/agentic-upgrade/different-major.md'), expect.stringContaining('/lib/upgrade/different-major.md'),
expect.stringContaining('/codemods.md'), expect.stringContaining('/codemods.md'),
expect.stringContaining('/version-15.md'), expect.stringContaining('/version-15.md'),
expect.stringContaining('/version-16.md'), expect.stringContaining('/version-16.md'),
...@@ -1256,13 +1256,13 @@ describe('agentic upgrade prompts', () => { ...@@ -1256,13 +1256,13 @@ describe('agentic upgrade prompts', () => {
) )
expect( expect(
copiedSources.some((source) => copiedSources.some((source) =>
source.includes('/agentic-upgrade/future-defaults.md') source.includes('/lib/upgrade/future-defaults.md')
) )
).toBe(false) ).toBe(false)
expect(normalizedBootstrapCalls()).toMatchInlineSnapshot(` expect(normalizedBootstrapCalls()).toMatchInlineSnapshot(`
[ [
[ [
"Read and follow "/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/shared.md" first. Attempt its applicable duplicate checks before changing files. If a check is unavailable, report it and continue. Stop only if you find equivalent work. Then read and follow every applicable instruction in "/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/different-major.md". "Read and follow "/tmp/next-upgrade-test/upgrade/shared.md" first. Attempt its applicable duplicate checks before changing files. If a check is unavailable, report it and continue. Stop only if you find equivalent work. Then read and follow every applicable instruction in "/tmp/next-upgrade-test/upgrade/different-major.md".
We're upgrading the app in "/workspace/app" from Next.js 14.1.1 to 16.3.5 because the installed version is affected by a published security advisory. We're upgrading the app in "/workspace/app" from Next.js 14.1.1 to 16.3.5 because the installed version is affected by a published security advisory.
...@@ -1293,7 +1293,7 @@ describe('agentic upgrade prompts', () => { ...@@ -1293,7 +1293,7 @@ describe('agentic upgrade prompts', () => {
const [guidePath, guide] = jest.mocked(writeFile).mock.calls[0] const [guidePath, guide] = jest.mocked(writeFile).mock.calls[0]
expect(String(guidePath).replace(/\\+/g, '/')).toBe( expect(String(guidePath).replace(/\\+/g, '/')).toBe(
'/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/different-major.md' '/tmp/next-upgrade-test/upgrade/different-major.md'
) )
expect(String(guide)).toMatch(/--skip-adoption --verbose$/) expect(String(guide)).toMatch(/--skip-adoption --verbose$/)
}) })
...@@ -1368,7 +1368,7 @@ describe('agentic upgrade prompts', () => { ...@@ -1368,7 +1368,7 @@ describe('agentic upgrade prompts', () => {
expect(writeFile).toHaveBeenCalledTimes(0) expect(writeFile).toHaveBeenCalledTimes(0)
expect( expect(
normalizedCopiedSources().some((source) => normalizedCopiedSources().some((source) =>
source.includes('/agentic-upgrade/future-defaults.md') source.includes('/lib/upgrade/future-defaults.md')
) )
).toBe(false) ).toBe(false)
expect( expect(
...@@ -1377,7 +1377,7 @@ describe('agentic upgrade prompts', () => { ...@@ -1377,7 +1377,7 @@ describe('agentic upgrade prompts', () => {
expect(normalizedBootstrapCalls()).toMatchInlineSnapshot(` expect(normalizedBootstrapCalls()).toMatchInlineSnapshot(`
[ [
[ [
"Read and follow "/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/shared.md" first. Attempt its applicable duplicate checks before changing files. If a check is unavailable, report it and continue. Stop only if you find equivalent work. Then read and follow every applicable instruction in "/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/same-major.md". "Read and follow "/tmp/next-upgrade-test/upgrade/shared.md" first. Attempt its applicable duplicate checks before changing files. If a check is unavailable, report it and continue. Stop only if you find equivalent work. Then read and follow every applicable instruction in "/tmp/next-upgrade-test/upgrade/same-major.md".
We're upgrading the app in "/workspace/app" from Next.js 16.2.12 to 16.3.5 because a newer stable Next.js release is available. We're upgrading the app in "/workspace/app" from Next.js 16.2.12 to 16.3.5 because a newer stable Next.js release is available.
...@@ -1414,16 +1414,16 @@ describe('agentic upgrade prompts', () => { ...@@ -1414,16 +1414,16 @@ describe('agentic upgrade prompts', () => {
) )
expect(normalizedBootstrapCalls().flat().join('\n')).toContain( expect(normalizedBootstrapCalls().flat().join('\n')).toContain(
'/agentic-upgrade/shared.md' '/upgrade/shared.md'
) )
expect(normalizedBootstrapCalls().flat().join('\n')).toContain( expect(normalizedBootstrapCalls().flat().join('\n')).toContain(
'/agentic-upgrade/same-major.md' '/upgrade/same-major.md'
) )
expect(readFile).toHaveBeenCalledTimes(0) expect(readFile).toHaveBeenCalledTimes(0)
expect(writeFile).toHaveBeenCalledTimes(0) expect(writeFile).toHaveBeenCalledTimes(0)
expect(normalizedCopiedSources()).toEqual([ expect(normalizedCopiedSources()).toEqual([
expect.stringContaining('/agentic-upgrade/shared.md'), expect.stringContaining('/lib/upgrade/shared.md'),
expect.stringContaining('/agentic-upgrade/same-major.md'), expect.stringContaining('/lib/upgrade/same-major.md'),
]) ])
}) })
...@@ -1447,11 +1447,11 @@ describe('agentic upgrade prompts', () => { ...@@ -1447,11 +1447,11 @@ describe('agentic upgrade prompts', () => {
) )
expect(normalizedBootstrapCalls().flat().join('\n')).toContain( expect(normalizedBootstrapCalls().flat().join('\n')).toContain(
'/agentic-upgrade/different-major.md' '/upgrade/different-major.md'
) )
expect( expect(
normalizedCopiedSources().some((source) => normalizedCopiedSources().some((source) =>
source.includes('/agentic-upgrade/future-defaults.md') source.includes('/lib/upgrade/future-defaults.md')
) )
).toBe(false) ).toBe(false)
}) })
...@@ -1476,11 +1476,11 @@ describe('agentic upgrade prompts', () => { ...@@ -1476,11 +1476,11 @@ describe('agentic upgrade prompts', () => {
) )
const prompt = normalizedBootstrapCalls().flat().join('\n') const prompt = normalizedBootstrapCalls().flat().join('\n')
expect(prompt).toContain('/agentic-upgrade/different-major.md') expect(prompt).toContain('/upgrade/different-major.md')
expect(prompt).toContain('/agentic-upgrade/future-defaults.md') expect(prompt).toContain('/upgrade/future-defaults.md')
expect(normalizedCopiedSources()).toEqual( expect(normalizedCopiedSources()).toEqual(
expect.arrayContaining([ expect.arrayContaining([
expect.stringContaining('/agentic-upgrade/future-defaults.md'), expect.stringContaining('/lib/upgrade/future-defaults.md'),
]) ])
) )
}) })
...@@ -1601,7 +1601,7 @@ describe('agentic upgrade prompts', () => { ...@@ -1601,7 +1601,7 @@ describe('agentic upgrade prompts', () => {
expect(normalizedFileWriteCalls()).toEqual(normalizedWriteFileCalls()) expect(normalizedFileWriteCalls()).toEqual(normalizedWriteFileCalls())
expect(normalizedCopiedSources()).toEqual( expect(normalizedCopiedSources()).toEqual(
expect.arrayContaining([ expect.arrayContaining([
expect.stringContaining('/agentic-upgrade/future-defaults.md'), expect.stringContaining('/lib/upgrade/future-defaults.md'),
]) ])
) )
...@@ -1612,7 +1612,7 @@ describe('agentic upgrade prompts', () => { ...@@ -1612,7 +1612,7 @@ describe('agentic upgrade prompts', () => {
{ {
"prompt": [ "prompt": [
[ [
"Read and follow "/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/shared.md" first. Attempt its applicable duplicate checks before changing files. If a check is unavailable, report it and continue. Stop only if you find equivalent work. Then read and follow every applicable instruction in "/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/same-major.md". "Read and follow "/tmp/next-upgrade-test/upgrade/shared.md" first. Attempt its applicable duplicate checks before changing files. If a check is unavailable, report it and continue. Stop only if you find equivalent work. Then read and follow every applicable instruction in "/tmp/next-upgrade-test/upgrade/same-major.md".
We're upgrading the app in "/workspace/app" from Next.js 16.2.0 to 16.4.0 because the Future policy applies the latest stable release and adopts its Future Defaults. We're upgrading the app in "/workspace/app" from Next.js 16.2.0 to 16.4.0 because the Future policy applies the latest stable release and adopts its Future Defaults.
...@@ -1620,7 +1620,7 @@ describe('agentic upgrade prompts', () => { ...@@ -1620,7 +1620,7 @@ describe('agentic upgrade prompts', () => {
Set \`experimental.agentUpgrade\` to "experimental-future" in the app's Next.js config as part of this upgrade. Preserve unrelated configuration. If the target Next.js version does not support this option, skip the setting and report why. Set \`experimental.agentUpgrade\` to "experimental-future" in the app's Next.js config as part of this upgrade. Preserve unrelated configuration. If the target Next.js version does not support this option, skip the setting and report why.
After completing and verifying the version update, read and follow "/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/future-defaults.md". After completing and verifying the version update, read and follow "/tmp/next-upgrade-test/upgrade/future-defaults.md".
Adopt these Future Defaults in order: Adopt these Future Defaults in order:
- Cache Components - Cache Components
- Read and follow "/tmp/next-upgrade-test/docs/01-app/02-guides/migrating-to-cache-components.md". - Read and follow "/tmp/next-upgrade-test/docs/01-app/02-guides/migrating-to-cache-components.md".
...@@ -1704,20 +1704,20 @@ describe('agentic upgrade prompts', () => { ...@@ -1704,20 +1704,20 @@ describe('agentic upgrade prompts', () => {
).toEqual( ).toEqual(
expect.arrayContaining([ expect.arrayContaining([
[ [
expect.stringContaining('/agentic-upgrade/future-defaults.md'), expect.stringContaining('/lib/upgrade/future-defaults.md'),
'/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/future-defaults.md', '/tmp/next-upgrade-test/upgrade/future-defaults.md',
], ],
]) ])
) )
expect(readFile).not.toHaveBeenCalled() expect(readFile).not.toHaveBeenCalled()
expect(normalizedFileWriteCalls()).not.toContainEqual([ expect(normalizedFileWriteCalls()).not.toContainEqual([
'/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/future-defaults.md', '/tmp/next-upgrade-test/upgrade/future-defaults.md',
expect.anything(), expect.anything(),
]) ])
expect(normalizedBootstrapCalls()).toMatchInlineSnapshot(` expect(normalizedBootstrapCalls()).toMatchInlineSnapshot(`
[ [
[ [
"Read and follow "/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/shared.md" first. Attempt its applicable duplicate checks before changing files. If a check is unavailable, report it and continue. Stop only if you find equivalent work. Then read and follow every applicable instruction in "/tmp/next-upgrade-test/docs/01-app/02-guides/upgrading/agentic-upgrade/future-defaults.md". "Read and follow "/tmp/next-upgrade-test/upgrade/shared.md" first. Attempt its applicable duplicate checks before changing files. If a check is unavailable, report it and continue. Stop only if you find equivalent work. Then read and follow every applicable instruction in "/tmp/next-upgrade-test/upgrade/future-defaults.md".
We're adopting the Future Defaults available to the app in "/workspace/app", which already uses Next.js 16.4.0. We're adopting the Future Defaults available to the app in "/workspace/app", which already uses Next.js 16.4.0.
......
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