[docs] Make v5 the default documentation version - #3714
Conversation
🦋 Changeset detectedLatest commit: a08bced The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Sim WorldSimulated world deterministic testing for races. Traces 🟠 world-sim scenario book — 1 fail of 41 total
Full trace: |
Serves `content/docs/v5` and `content/worlds/v5` unprefixed at /docs, /worlds and /cookbook, moves v4 under /v4, and puts What's new first in the v5 sidebar. The versioned source config drives both route trees (the root tree always renders `versionedSources.current`), so this is a `routePrefix` move plus source re-binding rather than a restructure. The only file moves are `app/[lang]/v5/**` → `app/[lang]/v4/**`. - Version switcher: `v5 (Latest)` / `v4 (Maintenance)`, `current: 'v5'`. - `pre-release-banner.tsx` becomes `maintenance-banner.tsx`. v4 pages carry an amber notice whose "Go to Workflow 5 (Latest)" link deep-links to the same page on the current version, falling back to the nearest section index for v4-only pages, and keep `robots: noindex, follow`. - Redirects: `/v5/*` to the unprefixed equivalent (bare `/v5` needs its own rule, since `:path*` expands to an empty Location). The world-docs and api-reference restructure rules are mirrored onto `/v4/docs/*`, and every page existing in only one tree gets a version-switcher fallback. - Both worlds route trees pass an explicit version into the shared page components, whose semantics flipped with the switch, so the smoke checks now assert the pairing: a " · v4" title marker and noindex on the maintenance routes, neither on the canonical ones, and a community world serving directly rather than self-redirecting. - The link lint's two URL spaces swap with the prefixes. Redirect destinations resolve against the real HTTP space, since redirects are matched before render-time href rewriting. - The two `/v4/...` links this makes expressible are restored: a v5 page cannot link to a v4 page while v4 is the unprefixed version. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sweep of everything that landed on main since the last content refresh, plus the spec-7 sealed log from #3634, which is not merged but is the default for v5. Spec 7 changes what a World declares, so the upgrade guide's Spec versions section is rewritten around `mintedSpecVersion()`. The accepted range widens back to two versions, because a deployment with `WORKFLOW_SEALED_LOG=0` stamps the one below, and both `SPEC_VERSION_CURRENT` and `SPEC_VERSION_SUPPORTS_SLOT_IDENTITY` become literals by another name for the purpose of declaring it: neither follows the setting. The new section says what a sealed log costs an implementer, which for most is nothing — a World allocating each position at the commit cannot leave a hole, so it never seals and never writes a `noop`. The obligation belongs to a World that pre-assigns positions, and the half that binds everyone is the reader's. `WORKFLOW_SEALED_LOG` is documented in runtime-tuning, taken verbatim from #3634 so whichever lands second is a no-op merge. The deep reference sections that PR writes, in event-sourcing and the World allocation contract, are left to it. Two optional World members shipped after the guide was written and were missing everywhere: - `events.createBatch` — in the World reference (interface and contract note), the upgrade guide's optional surface, and the skill. Implementing it is the declaration, so the note leads with atomicity per attempt and what a World must reject. - `runs.waitForTerminalStatus` — same three places. It is also what makes `await run.returnValue` a long poll rather than an interval, which is user-facing, so What's new gets it too. What's new also gains the batched suspension write and the pre-assigned positions behind it, both under faster-and-cheaper runs where they belong: neither has any API surface. Not addressed: `workflow.step.execute.duration`, the OpenTelemetry histogram added in #3526, has nowhere to go. The docs have no metrics reference at all, and inventing one for a single metric is a bigger call than this sweep. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
cbfd525 to
a08bced
Compare
🧪 E2E Test Results❌ Some tests failed ❌ Failed E2E Tests▲ Vercel Production (239 failed)astro-node (9 failed):
astro-quickjs (9 failed):
example-node (10 failed):
example-quickjs (9 failed):
express-node (9 failed):
express-quickjs (11 failed):
fastify-node (8 failed):
fastify-quickjs (11 failed):
hono-node (9 failed):
hono-quickjs (9 failed):
nest-node (11 failed):
nest-quickjs (11 failed):
nextjs-turbopack-node (5 failed):
nextjs-turbopack-quickjs (11 failed):
nextjs-webpack-node (8 failed):
nextjs-webpack-quickjs (9 failed):
nitro-node (10 failed):
nitro-quickjs (7 failed):
nuxt-node (9 failed):
nuxt-quickjs (8 failed):
sveltekit-node (9 failed):
sveltekit-quickjs (12 failed):
tanstack-start-node (7 failed):
tanstack-start-quickjs (10 failed):
vite-node (9 failed):
vite-quickjs (9 failed):
💻 Local Development (26 failed)nextjs-webpack-canary-node (26 failed):
🪟 Windows (1 failed)nextjs-turbopack-node (1 failed):
|
| Passed | Failed | Skipped | Total | |
|---|---|---|---|---|
| ❌ ▲ Vercel Production | 3339 | 239 | 742 | 4320 |
| ❌ 💻 Local Development | 3896 | 26 | 558 | 4480 |
| ✅ 📦 Local Production | 3922 | 0 | 558 | 4480 |
| ✅ 🐘 Local Postgres | 3922 | 0 | 558 | 4480 |
| ❌ 🪟 Windows | 319 | 1 | 0 | 320 |
| ✅ 🌐 Cross-language Conformance | 9 | 0 | 132 | 141 |
| ✅ vercel-multi-region | 27 | 0 | 0 | 27 |
| Total | 15434 | 266 | 2548 | 18248 |
Details by Category
❌ ▲ Vercel Production
| App | Passed | Failed | Skipped |
|---|---|---|---|
| ❌ astro-node | 123 | 9 | 28 |
| ❌ astro-quickjs | 123 | 9 | 28 |
| ❌ example-node | 122 | 10 | 28 |
| ❌ example-quickjs | 123 | 9 | 28 |
| ❌ express-node | 123 | 9 | 28 |
| ❌ express-quickjs | 121 | 11 | 28 |
| ❌ fastify-node | 124 | 8 | 28 |
| ❌ fastify-quickjs | 121 | 11 | 28 |
| ❌ hono-node | 123 | 9 | 28 |
| ❌ hono-quickjs | 123 | 9 | 28 |
| ❌ nest-node | 121 | 11 | 28 |
| ❌ nest-quickjs | 121 | 11 | 28 |
| ❌ nextjs-turbopack-node | 152 | 5 | 3 |
| ❌ nextjs-turbopack-quickjs | 146 | 11 | 3 |
| ❌ nextjs-webpack-node | 149 | 8 | 3 |
| ❌ nextjs-webpack-quickjs | 148 | 9 | 3 |
| ❌ nitro-node | 122 | 10 | 28 |
| ❌ nitro-quickjs | 125 | 7 | 28 |
| ❌ nuxt-node | 123 | 9 | 28 |
| ❌ nuxt-quickjs | 124 | 8 | 28 |
| ✅ python-node | 8 | 0 | 152 |
| ❌ sveltekit-node | 142 | 9 | 9 |
| ❌ sveltekit-quickjs | 139 | 12 | 9 |
| ❌ tanstack-start-node | 125 | 7 | 28 |
| ❌ tanstack-start-quickjs | 122 | 10 | 28 |
| ❌ vite-node | 123 | 9 | 28 |
| ❌ vite-quickjs | 123 | 9 | 28 |
❌ 💻 Local Development
| App | Passed | Failed | Skipped |
|---|---|---|---|
| ✅ astro-stable-node | 134 | 0 | 26 |
| ✅ astro-stable-quickjs | 134 | 0 | 26 |
| ✅ express-stable-node | 134 | 0 | 26 |
| ✅ express-stable-quickjs | 134 | 0 | 26 |
| ✅ fastify-stable-node | 134 | 0 | 26 |
| ✅ fastify-stable-quickjs | 134 | 0 | 26 |
| ✅ hono-stable-node | 134 | 0 | 26 |
| ✅ hono-stable-quickjs | 134 | 0 | 26 |
| ✅ nest-stable-node | 134 | 0 | 26 |
| ✅ nest-stable-quickjs | 134 | 0 | 26 |
| ✅ nextjs-turbopack-canary-node | 141 | 0 | 19 |
| ✅ nextjs-turbopack-canary-quickjs | 141 | 0 | 19 |
| ✅ nextjs-turbopack-stable-node | 160 | 0 | 0 |
| ✅ nextjs-turbopack-stable-quickjs | 160 | 0 | 0 |
| ❌ nextjs-webpack-canary-node | 115 | 26 | 19 |
| ✅ nextjs-webpack-canary-quickjs | 141 | 0 | 19 |
| ✅ nextjs-webpack-stable-node | 160 | 0 | 0 |
| ✅ nextjs-webpack-stable-quickjs | 160 | 0 | 0 |
| ✅ nitro-stable-node | 134 | 0 | 26 |
| ✅ nitro-stable-quickjs | 134 | 0 | 26 |
| ✅ nuxt-stable-node | 134 | 0 | 26 |
| ✅ nuxt-stable-quickjs | 134 | 0 | 26 |
| ✅ sveltekit-stable-node | 153 | 0 | 7 |
| ✅ sveltekit-stable-quickjs | 153 | 0 | 7 |
| ✅ tanstack-start-node | 134 | 0 | 26 |
| ✅ tanstack-start-quickjs | 134 | 0 | 26 |
| ✅ vite-stable-node | 134 | 0 | 26 |
| ✅ vite-stable-quickjs | 134 | 0 | 26 |
✅ 📦 Local Production
| App | Passed | Failed | Skipped |
|---|---|---|---|
| ✅ astro-stable-node | 134 | 0 | 26 |
| ✅ astro-stable-quickjs | 134 | 0 | 26 |
| ✅ express-stable-node | 134 | 0 | 26 |
| ✅ express-stable-quickjs | 134 | 0 | 26 |
| ✅ fastify-stable-node | 134 | 0 | 26 |
| ✅ fastify-stable-quickjs | 134 | 0 | 26 |
| ✅ hono-stable-node | 134 | 0 | 26 |
| ✅ hono-stable-quickjs | 134 | 0 | 26 |
| ✅ nest-stable-node | 134 | 0 | 26 |
| ✅ nest-stable-quickjs | 134 | 0 | 26 |
| ✅ nextjs-turbopack-canary-node | 141 | 0 | 19 |
| ✅ nextjs-turbopack-canary-quickjs | 141 | 0 | 19 |
| ✅ nextjs-turbopack-stable-node | 160 | 0 | 0 |
| ✅ nextjs-turbopack-stable-quickjs | 160 | 0 | 0 |
| ✅ nextjs-webpack-canary-node | 141 | 0 | 19 |
| ✅ nextjs-webpack-canary-quickjs | 141 | 0 | 19 |
| ✅ nextjs-webpack-stable-node | 160 | 0 | 0 |
| ✅ nextjs-webpack-stable-quickjs | 160 | 0 | 0 |
| ✅ nitro-stable-node | 134 | 0 | 26 |
| ✅ nitro-stable-quickjs | 134 | 0 | 26 |
| ✅ nuxt-stable-node | 134 | 0 | 26 |
| ✅ nuxt-stable-quickjs | 134 | 0 | 26 |
| ✅ sveltekit-stable-node | 153 | 0 | 7 |
| ✅ sveltekit-stable-quickjs | 153 | 0 | 7 |
| ✅ tanstack-start-node | 134 | 0 | 26 |
| ✅ tanstack-start-quickjs | 134 | 0 | 26 |
| ✅ vite-stable-node | 134 | 0 | 26 |
| ✅ vite-stable-quickjs | 134 | 0 | 26 |
✅ 🐘 Local Postgres
| App | Passed | Failed | Skipped |
|---|---|---|---|
| ✅ astro-stable-node | 134 | 0 | 26 |
| ✅ astro-stable-quickjs | 134 | 0 | 26 |
| ✅ express-stable-node | 134 | 0 | 26 |
| ✅ express-stable-quickjs | 134 | 0 | 26 |
| ✅ fastify-stable-node | 134 | 0 | 26 |
| ✅ fastify-stable-quickjs | 134 | 0 | 26 |
| ✅ hono-stable-node | 134 | 0 | 26 |
| ✅ hono-stable-quickjs | 134 | 0 | 26 |
| ✅ nest-stable-node | 134 | 0 | 26 |
| ✅ nest-stable-quickjs | 134 | 0 | 26 |
| ✅ nextjs-turbopack-canary-node | 141 | 0 | 19 |
| ✅ nextjs-turbopack-canary-quickjs | 141 | 0 | 19 |
| ✅ nextjs-turbopack-stable-node | 160 | 0 | 0 |
| ✅ nextjs-turbopack-stable-quickjs | 160 | 0 | 0 |
| ✅ nextjs-webpack-canary-node | 141 | 0 | 19 |
| ✅ nextjs-webpack-canary-quickjs | 141 | 0 | 19 |
| ✅ nextjs-webpack-stable-node | 160 | 0 | 0 |
| ✅ nextjs-webpack-stable-quickjs | 160 | 0 | 0 |
| ✅ nitro-stable-node | 134 | 0 | 26 |
| ✅ nitro-stable-quickjs | 134 | 0 | 26 |
| ✅ nuxt-stable-node | 134 | 0 | 26 |
| ✅ nuxt-stable-quickjs | 134 | 0 | 26 |
| ✅ sveltekit-stable-node | 153 | 0 | 7 |
| ✅ sveltekit-stable-quickjs | 153 | 0 | 7 |
| ✅ tanstack-start-node | 134 | 0 | 26 |
| ✅ tanstack-start-quickjs | 134 | 0 | 26 |
| ✅ vite-stable-node | 134 | 0 | 26 |
| ✅ vite-stable-quickjs | 134 | 0 | 26 |
❌ 🪟 Windows
| App | Passed | Failed | Skipped |
|---|---|---|---|
| ❌ nextjs-turbopack-node | 159 | 1 | 0 |
| ✅ nextjs-turbopack-quickjs | 160 | 0 | 0 |
✅ 🌐 Cross-language Conformance
| App | Passed | Failed | Skipped |
|---|---|---|---|
| ✅ python | 9 | 0 | 132 |
✅ vercel-multi-region
| App | Passed | Failed | Skipped |
|---|---|---|---|
| ✅ nextjs-turbopack | 27 | 0 | 0 |
📊 Workflow Benchmarks❌ The benchmark run for No benchmark results were produced. ℹ️ Metric definitions & methodologyMetrics — All timestamps are deployment-side; runs are triggered in-deployment, so the CI runner and api.vercel.com sit outside every measured window. TTFS = Cold starts stay in the numbers (real bursty-workload latency, inflates P75+); Best is the warm floor. |
Makes v5 the default documentation version for the 5.0.0 GA, and catches the v5 content up with everything that landed on
mainsince the v5 docs were last refreshed. Companion to #3090 (exit changeset pre mode) and #3091 (pin 4.x publishes toprevious).Version flip and routing
content/docs/v5andcontent/worlds/v5now serve unprefixed —/docs,/worlds,/cookbook— and v4 moves under a/v4prefix. The versioned source config drives both route trees (the root tree always rendersversionedSources.current), so this is aroutePrefixmove plus source re-binding, not a restructure. The only file moves areapp/[lang]/v5/**→app/[lang]/v4/**.v5 (Latest)/v4 (Maintenance);current: 'v5'.pre-release-banner.tsx→maintenance-banner.tsx. v4 pages carry an amber notice (with dark-mode styling) whose "Go to Workflow 5 (Latest)" link deep-links to the same page on the current version; v4-only pages land on the nearest section index via the fallback redirects. v4 pages keeprobots: noindex, follow.docs/next.config.ts):/v5/*→ unprefixed equivalent (permanent; bare/v5gets its own rule because:path*expands to an emptyLocationotherwise). The world-docs and api-reference restructure rules are mirrored onto/v4/docs/*, and every page that exists in only one tree has a version-switcher fallback (verified by diffing the two content trees)./v4worlds routes pass an explicit version into the shared page components, whose semantics flipped with the switch — smoke checks (assertWorldVersionMarkers,assertServesDirectly('/worlds/turso')) now guard the pairing so the canonical/worlds/*pages can't silently serve the maintenance version or self-redirect-loop again.docs/scripts/lint.ts): the two-space model swaps with the URL space; redirect destinations resolve against the real HTTP space since redirects are matched before render-time href rewriting.rewriteHrefForVersionpulls unprefixed hrefs on v4 pages into the/v4view, so a/v5/...href is the only way for v4 content to point at a current page. Three such links are kept deliberately; the lint models this.What moves with the flip
whats-newenters the v5 sidebar, first in the tree. [docs] v5 GA content: What's new, World upgrade guide, migration skills #3100 adds the page but leaves it out ofcontent/docs/v5/meta.json, so until this lands it is reachable only by URL.upgrading-to-v5moves fromapp/[lang]/v5/worlds/toapp/[lang]/worlds/, following the rest of the v5 worlds routes./v5view. [docs] v5 GA content: What's new, World upgrade guide, migration skills #3100 therefore phrases both as pointers to the version picker. Here they go back to being links — the v4 docs entry point in the What's new callout, and the v4 version of the code-transform page.editPathon the unprefixed docs route points atdocs/content/docs/v5/{path}.Catch-up with
mainSwept the 53 commits that landed since the last content refresh, and added what the docs were missing. Most changesets in that window are fixes, internal, or already documented by their own PR; three things were not.
Spec 7, the sealed log (#3634, not merged, default for v5). Positions are handed out ahead of the commit instead of being claimed by the write that fills them, so concurrent writers never contend and a wide fan-out stops serializing. The cost is a position whose writer dies, which the backend closes with a
noopevent that replay steps over without delivering it and without advancing the deterministic clock.upgrading-to-v5› Spec versions is rewritten aroundmintedSpecVersion(). The accepted range widens back to two versions, because a deployment withWORKFLOW_SEALED_LOG=0stamps the one below, and that makes bothSPEC_VERSION_CURRENTandSPEC_VERSION_SUPPORTS_SLOT_IDENTITYliterals by another name for declaring it — neither follows the setting. This replaces what [docs] v5 GA content: What's new, World upgrade guide, migration skills #3100 said for spec 6, which was that exactly one version is accepted.noopevents" subsection says what this costs an implementer, which for most is nothing: a World allocating each position at the commit cannot leave a hole, so it never seals and never emits anoop. The obligation belongs to a World that pre-assigns positions; the half that binds everyone is the reader's.WORKFLOW_SEALED_LOGis documented in runtime-tuning, taken verbatim from Add support for 'noop' event type - spec version 7 #3634 so whichever lands second is a no-op merge. The deep reference sections that PR writes — inevent-sourcingand the World allocation contract — are left to it, so this does not duplicate them.events.createBatch(#3025). An optional World method appending an ordered list of events in one durable write with per-event outcomes. It was documented only as a changelog page and an env var, so the World reference had no mention of a method a World author has to decide about. Added to the interface snippet, to the Key Implementation Details as a contract note (atomicity per attempt, what a World must reject, the one legal same-entity pair), to the upgrade guide's optional surface, and to the skill.runs.waitForTerminalStatus(#3570). Also missing from the upgrade guide and the skill. It is what makesawait run.returnValuea long poll rather than an interval, which is user-facing, so What's new gets that as an entry.What's new also gains the batched suspension write and the positions change under faster-and-cheaper runs, where they belong: neither has any API surface.
Not addressed.
workflow.step.execute.duration, the OpenTelemetry histogram from #3526, has nowhere to go — the docs carry no metrics reference at all, and inventing one for a single metric is a bigger call than this sweep. Flagging rather than guessing.Verification
Link lint passes with 0 errors.
pnpm buildcompiles, with/en/docs/whats-newprerendered under the unprefixed route,/[lang]/v4/docs/[[...slug]]serving the maintenance tree, andƒ /[lang]/worlds/upgrading-to-v5.Docs Preview
Links will be added from the
workflow-docspreview once it deploys.🤖 Generated with Claude Code