Unverified Commit 9ff761f2 authored by Sebastian "Sebbie" Silbermann's avatar Sebastian "Sebbie" Silbermann Committed by GitHub

Stop requiring build-all when bootstrapping a fresh clone or worktree (#100600)

The agent instructions required a full `pnpm build-all` (JS and Rust)
after every worktree creation or branch switch. That is unnecessary when
bootstrapping a new clone or worktree: `pnpm install` already pulls in
recent published native bindings, so there is nothing to build until
source changes.

The new guidance:

- Bootstrapping a new clone or worktree does not start with `pnpm
build-all`. Build only what your work changes: `pnpm --filter=next
build` for core-only JS edits, `pnpm build` when JS changes span
packages.
- Switching branches or pulling can still require a build when it moves
JS or Rust source relative to your build outputs; rebuild the affected
parts before running tests.
- `pnpm build-all` is reserved for Rust/Turbopack changes, or for when
Next.js fails to start because native binding changes landed on canary
after the last npm publish (cross-referenced from the Stale Native
Binary section).

The `backport-pr` skill repeated the old branch-switch rule and is
updated to the same policy.

<!-- NEXT_JS_LLM -->
Co-authored-by: 's avatarClaude Code <noreply@anthropic.com>
parent 7657545d
...@@ -67,8 +67,11 @@ branch. ...@@ -67,8 +67,11 @@ branch.
git switch -c backport-<pr-number>-to-<target-branch> origin/<target-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 Bootstrapping this checkout does not require `pnpm build-all` since
integration tests unless the user explicitly limits the task to preparing the `pnpm install` pulls in recent native bindings. Before running Next.js
integration tests, build what the branch switch and cherry-pick changed:
`pnpm build` for JS changes, `pnpm build-all` only for Rust/Turbopack
changes. Skip builds entirely if the task is limited to preparing the
cherry-pick or PR. cherry-pick or PR.
5. Cherry-pick the landed commit with provenance: 5. Cherry-pick the landed commit with provenance:
......
...@@ -72,7 +72,7 @@ For iterative Next.js source development, default to watch mode plus the explici ...@@ -72,7 +72,7 @@ For iterative Next.js source development, default to watch mode plus the explici
**Default agent rule:** If you are changing Next.js source, start `pnpm --filter=next dev` in a separate terminal session before making edits (unless it is already running). If you skip this, explicitly state why (for example: docs-only, test-only, read-only investigation, or CI-only analysis). **Default agent rule:** If you are changing Next.js source, start `pnpm --filter=next dev` in a separate terminal session before making edits (unless it is already running). If you skip this, explicitly state why (for example: docs-only, test-only, read-only investigation, or CI-only analysis).
**Test-only changes:** When changes are confined to `test/`, do not start `pnpm --filter=next dev` or rebuild Next.js. Run the relevant mode-specific tests directly; the test harness builds test fixtures as needed. This assumes the workspace is already bootstrapped and framework build outputs are current. A fresh checkout, branch switch, or missing/stale build outputs still requires a bootstrap build. **Test-only changes:** When changes are confined to `test/`, do not start `pnpm --filter=next dev` or rebuild Next.js. Run the relevant mode-specific tests directly; the test harness builds test fixtures as needed. This assumes the workspace is already bootstrapped and framework build outputs are current. Missing or stale framework build outputs still require a build.
**1. Start watch build in background:** **1. Start watch build in background:**
...@@ -102,14 +102,9 @@ pnpm test-start-webpack test/path/to/test.ts ...@@ -102,14 +102,9 @@ pnpm test-start-webpack test/path/to/test.ts
**For type errors only:** Use `pnpm --filter=next types` (~10s) instead of `pnpm --filter=next build` (~60s). **For type errors only:** Use `pnpm --filter=next types` (~10s) instead of `pnpm --filter=next build` (~60s).
After the workspace is bootstrapped, prefer `pnpm --filter=next build` when edits are limited to core Next.js files. Use full `pnpm build-all` for branch switches/bootstrap, before CI push for framework changes, or when changes span multiple packages. Test-only changes do not require a framework rebuild before CI push. **Bootstrapping a new clone or worktree does not require `pnpm build-all`.** `pnpm install` already pulls in recent published native bindings, so build only what your work changes: `pnpm --filter=next build` when edits are limited to core Next.js files, `pnpm build` when changes span multiple JS packages, and `pnpm build-all` only when changes include Rust/Turbopack code. Test-only changes do not require a framework rebuild before CI push.
**Always run a full bootstrap build after switching branches:** **Switching branches or pulling can still require a build** when it moves JS or Rust source relative to your build outputs: rebuild the affected parts before running tests (`pnpm build` for JS, `pnpm build-all` for Rust). If Next.js fails to start afterwards, the published native bindings may lag canary; see [Stale Native Binary](#stale-native-binary).
```bash
git checkout <branch>
pnpm build-all # Sets up outputs for dependent packages (Turborepo dedupes if unchanged)
```
## Bundler Selection ## Bundler Selection
...@@ -460,12 +455,13 @@ npx eslint --config eslint.config.mjs --fix <files> ...@@ -460,12 +455,13 @@ npx eslint --config eslint.config.mjs --fix <files>
## Rebuilding Before Running Tests ## Rebuilding Before Running Tests
When running Next.js integration tests, rebuild if framework source files have changed, not merely test files: Rebuild before running Next.js integration tests when framework source files changed, whether from your own edits or from a branch switch or pull that moved JS or Rust source:
- **First run after branch switch/bootstrap (or if unsure)?** → `pnpm build-all`
- **Only edited `test/` files, with current framework build outputs?** → No framework rebuild or watch build needed; run the relevant tests directly. - **Only edited `test/` files, with current framework build outputs?** → No framework rebuild or watch build needed; run the relevant tests directly.
- **Edited only core Next.js files (`packages/next/**`) after bootstrap?** → `pnpm --filter=next build` - **Changed only core Next.js files (`packages/next/**`)?** → `pnpm --filter=next build`
- **Edited Next.js code or Turbopack (Rust)?** → `pnpm build-all` - **Changed JS across multiple packages?** → `pnpm build`
- **Changed Turbopack or other Rust code?** → `pnpm build-all`
- **Next.js fails to start with Turbopack errors?** → The published canary native bindings may lag the source; see [Stale Native Binary](#stale-native-binary).
## Development Anti-Patterns ## Development Anti-Patterns
...@@ -519,6 +515,8 @@ Core runtime/bundling rules (always apply; skills above expand on these with ver ...@@ -519,6 +515,8 @@ Core runtime/bundling rules (always apply; skills above expand on these with ver
If Turbopack produces unexpected errors after switching branches or pulling, check if `packages/next-swc/native/*.node` is stale. Delete it and run `pnpm install` to get the npm-published binary instead of a locally-built one. If Turbopack produces unexpected errors after switching branches or pulling, check if `packages/next-swc/native/*.node` is stale. Delete it and run `pnpm install` to get the npm-published binary instead of a locally-built one.
`pnpm install` already pulls in the latest published native bindings, which usually track canary closely. If Next.js still fails to start after that, native binding changes may have landed on canary after the last npm publish. Build the native bindings from source with `pnpm build-all`.
### Documentation Code Blocks ### Documentation Code Blocks
- When adding `highlight={...}` attributes to code blocks, carefully count the actual line numbers within the code block - When adding `highlight={...}` attributes to code blocks, carefully count the actual line numbers within the code block
......
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