Unverified Commit f0760ec6 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

[lts-active] Backport additional documentation fixes since v16.4.0 (#100262)

## Summary

- Backport #100033 so the `ensureStatic` TypeScript hints link to the
API reference and accurately describe prefetch behavior.
- Backport #100020 and #100135 so the agent-feedback documentation and
the generated managed block stay synchronized, use the workspace-safe
reporting command, and do not imply that agents may skip verification.
- Preserve the LTS `create-next-app` generator because its prerequisite
agent-feedback scaffolding change is not part of this backport.
- Intentionally exclude #99786 because it also changes the public
`router.prefetch` types and typed-route behavior.

## Verification

- `pnpm prettier --with-node-modules --ignore-path .prettierignore
--check <changed files>`
- `pnpm exec eslint --config eslint.config.mjs <changed files>`
- `pnpm exec jest --runInBand
packages/next/src/server/lib/generate-agent-files.test.ts` (11 tests)
- Not completed: `pnpm build-all` (the isolated worktree lacks
package-local `node_modules` binaries such as `microbundle` and `ncc`)

<!-- NEXT_JS_LLM -->

---------
Co-authored-by: 's avatarvercel-gh-bot-2[bot] <282331341+vercel-gh-bot-2[bot]@users.noreply.github.com>
Co-authored-by: 's avatarvercel-gh-bot-3[bot] <282332853+vercel-gh-bot-3[bot]@users.noreply.github.com>
Co-authored-by: 's avatarvercel-gh-bot-5[bot] <312521305+vercel-gh-bot-5[bot]@users.noreply.github.com>
parent 845007af
...@@ -98,9 +98,11 @@ During the current user request, retain anonymized facts as feedback candidates ...@@ -98,9 +98,11 @@ During the current user request, retain anonymized facts as feedback candidates
- Missing, unclear, or conflicting documentation - Missing, unclear, or conflicting documentation
- Unexpected CLI, codemod, Skill, or upgrade behavior and non-obvious workarounds - Unexpected CLI, codemod, Skill, or upgrade behavior and non-obvious workarounds
Continue the current user request without reporting immediately. Ignore routine debugging and unverified changes. Never retain code, logs, paths, URLs, secrets, personal information, or project-specific data. Continue the current user request without reporting immediately. Routine debugging is not feedback. Verify changes before retaining them as feedback candidates. Never retain code, logs, paths, URLs, secrets, personal information, or project-specific data.
Before the final response, run one reporting pass. If candidates remain, from this file's directory run `node node_modules/next/dist/bin/next internal agent-feedback-instructions` once without piping or truncating its output. Follow its output or error guidance. If a network sandbox blocks it, retry with network access; if it still returns no output, continue normally. Retain qualifying friction even if it is later fixed or worked around; record the final outcome during the reporting pass.
Before the final response, run one reporting pass. If candidates remain, from this file's directory run `npx --no-install next internal agent-feedback-instructions` once without piping or truncating its output. Follow its output or error guidance. If a network sandbox blocks it, retry with network access; if it still returns no output, continue normally.
<!-- END:nextjs-agent-feedback --> <!-- END:nextjs-agent-feedback -->
``` ```
......
...@@ -53,9 +53,11 @@ During the current user request, retain anonymized facts as feedback candidates ...@@ -53,9 +53,11 @@ During the current user request, retain anonymized facts as feedback candidates
- Missing, unclear, or conflicting documentation - Missing, unclear, or conflicting documentation
- Unexpected CLI, codemod, Skill, or upgrade behavior and non-obvious workarounds - Unexpected CLI, codemod, Skill, or upgrade behavior and non-obvious workarounds
Continue the current user request without reporting immediately. Ignore routine debugging and unverified changes. Never retain code, logs, paths, URLs, secrets, personal information, or project-specific data. Continue the current user request without reporting immediately. Routine debugging is not feedback. Verify changes before retaining them as feedback candidates. Never retain code, logs, paths, URLs, secrets, personal information, or project-specific data.
Before the final response, run one reporting pass. If candidates remain, from this file's directory run `node node_modules/next/dist/bin/next internal agent-feedback-instructions` once without piping or truncating its output. Follow its output or error guidance. If a network sandbox blocks it, retry with network access; if it still returns no output, continue normally. Retain qualifying friction even if it is later fixed or worked around; record the final outcome during the reporting pass.
Before the final response, run one reporting pass. If candidates remain, from this file's directory run `npx --no-install next internal agent-feedback-instructions` once without piping or truncating its output. Follow its output or error guidance. If a network sandbox blocks it, retry with network access; if it still returns no output, continue normally.
<!-- END:nextjs-agent-feedback --> <!-- END:nextjs-agent-feedback -->
``` ```
......
...@@ -123,3 +123,27 @@ describe.each([ ...@@ -123,3 +123,27 @@ describe.each([
expect(fs.readFileSync(path.join(dir, 'AGENTS.md'), 'utf-8')).toBe(content) expect(fs.readFileSync(path.join(dir, 'AGENTS.md'), 'utf-8')).toBe(content)
}) })
}) })
describe('agent feedback block wording', () => {
let dir: string
beforeEach(() => {
dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-files-'))
})
afterEach(() => {
fs.rmSync(dir, { recursive: true, force: true })
})
it('does not tell agents to ignore unverified changes', () => {
expect(writeAgentFeedbackFiles(dir).agentsMd).toBe('created')
const content = fs.readFileSync(path.join(dir, 'AGENTS.md'), 'utf-8')
expect(content).toContain(
'Verify changes before retaining them as feedback candidates.'
)
expect(content).not.toContain(
'Ignore routine debugging and unverified changes.'
)
})
})
...@@ -56,11 +56,11 @@ During the current user request, retain anonymized facts as feedback candidates ...@@ -56,11 +56,11 @@ During the current user request, retain anonymized facts as feedback candidates
- Missing, unclear, or conflicting documentation - Missing, unclear, or conflicting documentation
- Unexpected CLI, codemod, Skill, or upgrade behavior and non-obvious workarounds - Unexpected CLI, codemod, Skill, or upgrade behavior and non-obvious workarounds
Continue the current user request without reporting immediately. Ignore routine debugging and unverified changes. Never retain code, logs, paths, URLs, secrets, personal information, or project-specific data. Continue the current user request without reporting immediately. Routine debugging is not feedback. Verify changes before retaining them as feedback candidates. Never retain code, logs, paths, URLs, secrets, personal information, or project-specific data.
Keep a qualifying candidate through the reporting pass even if you resolve or work around it. A successful fix changes the report outcome; it does not erase the friction that qualified it. Retain qualifying friction even if it is later fixed or worked around; record the final outcome during the reporting pass.
Before the final response, run one reporting pass. If candidates remain, from this file's directory run \`node node_modules/next/dist/bin/next internal agent-feedback-instructions\` once without piping or truncating its output. Follow its output or error guidance. If a network sandbox blocks it, retry with network access; if it still returns no output, continue normally. Before the final response, run one reporting pass. If candidates remain, from this file's directory run \`npx --no-install next internal agent-feedback-instructions\` once without piping or truncating its output. Follow its output or error guidance. If a network sandbox blocks it, retry with network access; if it still returns no output, continue normally.
${AGENT_FEEDBACK_END_MARKER}` ${AGENT_FEEDBACK_END_MARKER}`
} }
......
...@@ -25,6 +25,8 @@ import { RenderStage } from '../app-render/staged-rendering' ...@@ -25,6 +25,8 @@ import { RenderStage } from '../app-render/staged-rendering'
* *
* Unlike `connection()`, it does not mark the subtree as request-dependent — * Unlike `connection()`, it does not mark the subtree as request-dependent —
* content below `await prefetch()` remains fully cacheable. * content below `await prefetch()` remains fully cacheable.
*
* Read more: [Next.js Docs: `prefetch`](https://nextjs.org/docs/app/api-reference/functions/prefetch)
*/ */
export function prefetch(): Promise<void> { export function prefetch(): Promise<void> {
const workStore = workAsyncStorage.getStore() const workStore = workAsyncStorage.getStore()
...@@ -177,6 +179,8 @@ export function prefetch(): Promise<void> { ...@@ -177,6 +179,8 @@ export function prefetch(): Promise<void> {
* *
* Unlike `connection()`, it does not mark the subtree as request-dependent — * Unlike `connection()`, it does not mark the subtree as request-dependent —
* content below `await navigation()` remains fully cacheable. * content below `await navigation()` remains fully cacheable.
*
* Read more: [Next.js Docs: `navigation`](https://nextjs.org/docs/app/api-reference/functions/navigation)
*/ */
export function navigation(): Promise<void> { export function navigation(): Promise<void> {
const workStore = workAsyncStorage.getStore() const workStore = workAsyncStorage.getStore()
......
...@@ -161,7 +161,7 @@ const API_DOCS: Record< ...@@ -161,7 +161,7 @@ const API_DOCS: Record<
}, },
prefetch: { prefetch: {
description: `Controls prefetching behavior for this segment. Some options are experimental and may change.`, description: `Controls prefetching behavior for this segment. Some options are experimental and may change.`,
link: '(docs coming soon)', link: 'https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/prefetch',
type: `"auto" | "partial" | "force-disabled"`, type: `"auto" | "partial" | "force-disabled"`,
options: { options: {
auto: 'Default. Framework decides based on instant validation and segment configuration. You do not need to set this explicitly.', auto: 'Default. Framework decides based on instant validation and segment configuration. You do not need to set this explicitly.',
...@@ -173,7 +173,7 @@ const API_DOCS: Record< ...@@ -173,7 +173,7 @@ const API_DOCS: Record<
}, },
ensureStatic: { ensureStatic: {
description: `Controls which rendering phases require static output for this segment. This option is experimental and may change.`, description: `Controls which rendering phases require static output for this segment. This option is experimental and may change.`,
link: '(docs coming soon)', link: 'https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic',
type: `"auto" | "shell" | "prefetch" | "navigation" | false`, type: `"auto" | "shell" | "prefetch" | "navigation" | false`,
options: { options: {
'"auto"': '"auto"':
......
...@@ -220,14 +220,12 @@ describe('agent-feedback auto-generate on next dev (enabled)', () => { ...@@ -220,14 +220,12 @@ describe('agent-feedback auto-generate on next dev (enabled)', () => {
) )
expect(content).toContain('- Unexpected CLI, codemod, Skill') expect(content).toContain('- Unexpected CLI, codemod, Skill')
expect(content).toContain( expect(content).toContain(
'Keep a qualifying candidate through the reporting pass even if you resolve or work around it.' 'Retain qualifying friction even if it is later fixed or worked around; record the final outcome during the reporting pass.'
) )
expect(content).toContain( expect(content).toContain(
'A successful fix changes the report outcome; it does not erase the friction that qualified it.' 'npx --no-install next internal agent-feedback-instructions'
)
expect(content).toContain(
'node node_modules/next/dist/bin/next internal agent-feedback-instructions'
) )
expect(content).not.toContain('node node_modules/next/dist/bin/next')
expect(content).toContain('without piping or truncating its output') expect(content).toContain('without piping or truncating its output')
expect(content).toContain( expect(content).toContain(
'Before the final response, run one reporting pass' 'Before the final response, run one reporting pass'
......
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