Uh oh!
There was an error while loading. Please reload this page.
fix(docs): version-switcher fallback redirects for pages missing in one version - #3003
Merged
Merged
Conversation
|
Contributor
VaguelySerious
approved these changes
Jul 20, 2026
Uh oh!
There was an error while loading. Please reload this page.
Contributor
No backport to The commit only modifies To override, re-run the Backport to stable workflow manually via |
pranaygp added a commit
that referenced
this pull request
Jul 21, 2026
* origin/main: (21 commits) docs(agents): note lint/format/typecheck are advisory, not blocking (#2886) Retry transient connection timeouts (#3013) fix(world-vercel): append caller User-Agent products instead of discarding them (#2998) [ci] Enable NestJS e2e-vercel-prod and add to docs as "experimental" (#3011) [ci] Benchmark comment: Best column + best/p75/p99 deltas (drop Avg/P10) (#3005) docs: fall back to first child page for sidebar folders without an index (#3009) [nest] Fix NestJS Vercel build output (#2988) Avoid resolving run data for background steps (#2993) chore(docs): update @vercel/geistdocs to 1.14.0 (#3002) fix(docs): add version-switcher fallback redirects for pages missing in one version (#3003) ci: update opencode to 1.18.4 and switch backport AI model to claude-fable-5 (#3006) fix(core): batch stream writes via writeMulti (#2995) perf(core): cache port discovery in step invocations for self-hosted worlds (#2996) feat(web-shared): Alt+hover span measurement in the new trace viewer (#2985) fix(world-postgres): throw EntityConflictError on duplicate run_created (#2983) [ci] Run benchmarks in-deployment to avoid proxy overhead (#2967) Enable additional perf optimizations when correctness guarantees are met (#2970) perf(core): prepare replay payloads concurrently (#2980) Fix dotted tsconfig alias workflow discovery (#2963) Adjust helper position on trace viewer (#2968) ...
pranaygp added a commit
that referenced
this pull request
Jul 21, 2026
* origin/main: test: regression coverage for hook.resume() from isolated route bundles (o2flow beta.26 incident) (#3001) docs(agents): note lint/format/typecheck are advisory, not blocking (#2886) Retry transient connection timeouts (#3013) fix(world-vercel): append caller User-Agent products instead of discarding them (#2998) [ci] Enable NestJS e2e-vercel-prod and add to docs as "experimental" (#3011) [ci] Benchmark comment: Best column + best/p75/p99 deltas (drop Avg/P10) (#3005) docs: fall back to first child page for sidebar folders without an index (#3009) [nest] Fix NestJS Vercel build output (#2988) Avoid resolving run data for background steps (#2993) chore(docs): update @vercel/geistdocs to 1.14.0 (#3002) fix(docs): add version-switcher fallback redirects for pages missing in one version (#3003) ci: update opencode to 1.18.4 and switch backport AI model to claude-fable-5 (#3006) fix(core): batch stream writes via writeMulti (#2995)
pranaygp added a commit
that referenced
this pull request
Jul 22, 2026
* origin/main: (162 commits) Implement `max_events` per run limit (#2986) [core] Enforce maxRetries for steps that time out (#3035) [world-vercel] Idempotent retry policy for stream close (5xx retriable) (#3038) [world] Guard hook_received against a concurrent run termination (#2987) docs: fix stale/incorrect v5 API reference details (#3017) Default WORKFLOW_PRECONDITION_GUARD on (#2946) docs: replace migration guides with a Comparisons section (#2676) feat(core): add experimental Hook minimum retention (#2865) test: regression coverage for hook.resume() from isolated route bundles (o2flow beta.26 incident) (#3001) docs(agents): note lint/format/typecheck are advisory, not blocking (#2886) Retry transient connection timeouts (#3013) fix(world-vercel): append caller User-Agent products instead of discarding them (#2998) [ci] Enable NestJS e2e-vercel-prod and add to docs as "experimental" (#3011) [ci] Benchmark comment: Best column + best/p75/p99 deltas (drop Avg/P10) (#3005) docs: fall back to first child page for sidebar folders without an index (#3009) [nest] Fix NestJS Vercel build output (#2988) Avoid resolving run data for background steps (#2993) chore(docs): update @vercel/geistdocs to 1.14.0 (#3002) fix(docs): add version-switcher fallback redirects for pages missing in one version (#3003) ci: update opencode to 1.18.4 and switch backport AI model to claude-fable-5 (#3006) ... # Conflicts: # docs/content/docs/v4/deploying/meta.json # docs/content/docs/v5/deploying/meta.json # packages/core/src/runtime.ts # packages/world-local/src/index.ts # packages/world-postgres/src/index.ts # packages/world/src/events.ts # packages/world/src/interfaces.ts # packages/world/src/recovery.ts # workbench/nest/src/main.ts # workbench/sveltekit/src/hooks.server.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The docs version switcher swaps the
/v5route prefix without checking that the page exists in the target version (resolveRouteHrefin@vercel/geistdocsis a pure prefix swap), so any page that exists in only one docs tree 404s on switch. Example on production: https://workflow-sdk.dev/v5/docs/configuration → switch to v4 → 404 at/docs/configuration.This adds fallback redirects in
docs/next.config.tsfor every page that currently exists in only one version, generated by diffingdocs/content/docs/v4againstdocs/content/docs/v5. Each lands on the nearest equivalent in the target version (usually the section index):v5-only pages (v5 → v4 switch),
/docs/...:configuration+ all subpages →/docs/deployingapi-reference/workflow/set-attributes→/docs/api-reference/workflowapi-reference/workflow-errors/precondition-failed-error→ section indexapi-reference/workflow-runtime/world/analytics→ section indexchangelog/{attributes-mvp,eager-processing,step-message-ownership}→/docs/changelogerrors/abort-signal-timeout-in-workflow→/docs/errorsfoundations/cancellation,how-it-works/cancellation→/docs/foundations(v4 has no how-it-works index)getting-started/react-router(+v7/v8) →/docs/getting-startedinternal/{nitro-native-build,nitro-web-ui,serializable-abort-controller}→/docs/internalobservability/{attributes,tracing}→/docs/observabilityv4-only pages (v4 → v5 switch),
/v5/...:api-reference/workflow-runtime/step-entrypoint→/v5/docs/api-reference/workflow-runtimecookbook/advanced/distributed-abort-controller→/v5/cookbook(no/v5/cookbook/advancedindex)All fallbacks are
permanent: false— they need revisiting when content is backported or when v5 becomes the default version (which swaps the trees served at/docs).Also fixes a related live 404:
/docs/api-reference/workflow/experimental-set-attributesredirected to/docs/api-reference/workflow/set-attributes, which doesn't exist on v4. It now lands on the section index directly (no redirect chain through the new fallback).The proper fix for the whole class is upstream in geistdocs (version switcher falling back to the nearest existing page in the target tree); these redirects fix production now.
Testing
pnpm --filter docs buildnext start+ curl: all 16 fallback sources return 307 to their documented destinations, every destination returns 200, and existing pages (e.g./docs/changelog/resilient-start,/cookbook/advanced/distributed-abort-controller,/v5/docs/configuration) still return 200No changeset needed: docs-app-only change (
pnpm changeset status --since=origin/mainpasses).