Add workflow versioning docs#2010
Merged
Merged
Conversation
Contributor
🦋 Changeset detectedLatest commit: 7eff96c 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 |
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
workflow with 1 step💻 Local Development
workflow with 10 sequential steps💻 Local Development
workflow with 25 sequential steps💻 Local Development
workflow with 50 sequential steps💻 Local Development
Promise.all with 10 concurrent steps💻 Local Development
Promise.all with 25 concurrent steps💻 Local Development
Promise.all with 50 concurrent steps💻 Local Development
Promise.race with 10 concurrent steps💻 Local Development
Promise.race with 25 concurrent steps💻 Local Development
Promise.race with 50 concurrent steps💻 Local Development
workflow with 10 sequential data payload steps (10KB)💻 Local Development
workflow with 25 sequential data payload steps (10KB)💻 Local Development
workflow with 50 sequential data payload steps (10KB)💻 Local Development
workflow with 10 concurrent data payload steps (10KB)💻 Local Development
workflow with 25 concurrent data payload steps (10KB)💻 Local Development
workflow with 50 concurrent data payload steps (10KB)💻 Local Development
Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
stream pipeline with 5 transform steps (1MB)💻 Local Development
10 parallel streams (1MB each)💻 Local Development
fan-out fan-in 10 streams (1MB each)💻 Local Development
SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
❌ Some benchmark jobs failed:
Check the workflow run for details. |
Contributor
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests▲ Vercel Production (4 failed)astro (1 failed):
hono (2 failed):
nextjs-webpack (1 failed):
🐘 Local Postgres (2 failed)nextjs-webpack-stable-lazy-discovery-disabled (1 failed):
nextjs-webpack-stable-lazy-discovery-enabled (1 failed):
Details by Category❌ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
❌ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
❌ Some E2E test jobs failed:
Check the workflow run for details. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new "Versioning" Foundations page (v4 and v5) explaining default run pinning to deployments, recovery via cancel + rerun, opting into newer code with deploymentId: "latest", and carrying serializable state/streams across child-run continuations. Existing references to deploymentId: "latest" and versioning behavior are linked back to the new page. Cookbook pages also pick up callouts about long-lived / multi-turn patterns and, on v5 only, are updated to reflect that start() can now be called directly inside "use workflow" functions (via #1491), while v4 retains the step-wrapped pattern.
Changes:
- New
foundations/versioning.mdxfor both v4 and v5, plus meta.json + index.mdx + linkbacks fromvercel-world,start.mdx, andcode-transform.mdx. - v5 cookbook + migration guides updated to drop
"use step"wrappers aroundstart()in favor of callingstart()directly from the workflow function; v4 keeps the step-wrapped pattern. - Added "Versioning" callouts to scheduling, durable-agent, ai-sdk, chat-sdk, and sandbox cookbooks; fixed a few small wording/grammar issues in
code-transform.mdx.
Reviewed changes
Copilot reviewed 32 out of 32 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/content/docs/v5/foundations/versioning.mdx | New Foundations page explaining run pinning, recovery, and explicit upgrade boundaries. |
| docs/content/docs/v4/foundations/versioning.mdx | v4 counterpart; uses step-wrapped continueDigest/continueExportOnLatest helpers. |
| docs/content/docs/v{4,5}/foundations/{meta.json,index.mdx} | Surface the new Versioning page in nav and the foundations index. |
| docs/content/docs/v{4,5}/deploying/world/vercel-world.mdx | Link the deployment-pinning section to the new Versioning page. |
| docs/content/docs/v{4,5}/how-it-works/code-transform.mdx | Link "atomic versioning" reference; fix "function assume" / "from being upgraded" wording. |
| docs/content/docs/v{4,5}/api-reference/workflow-api/start.mdx | Soften "Vercel-specific" to "Vercelism", mention possible version rename, link Versioning. v5 also notes native workflow-context start(). |
| docs/content/docs/v5/foundations/starting-workflows.mdx | Note v5 can call start() from workflows; link Composition + Versioning. |
| docs/content/docs/v5/cookbook/common-patterns/workflow-composition.mdx | Replace step-wrapped child spawn with direct start() call. |
| docs/content/docs/v5/cookbook/advanced/child-workflows.mdx | Inline batched start() calls; rename spawnReportChunk → startReportChunk; update tips. |
| docs/content/docs/v{4,5}/cookbook/common-patterns/scheduling.mdx | Callout linking to Versioning for long-lived schedules. |
| docs/content/docs/v{4,5}/cookbook/agent-patterns/durable-agent.mdx | Callout linking to Versioning for multi-turn agents. |
| docs/content/docs/v{4,5}/cookbook/integrations/{ai-sdk,chat-sdk,sandbox}.mdx | Callouts linking to Versioning for long-lived sessions. |
| docs/content/docs/v4/cookbook/common-patterns/workflow-composition.mdx | Update deploymentId: "latest" callout wording + link to Versioning. |
| docs/content/docs/v4/cookbook/advanced/child-workflows.mdx | Link Versioning from the deploymentId: "latest" tip. |
| docs/content/docs/v4/changelog/eager-processing.mdx | Reword to "step-wrapped start() helper" to match v4 phrasing. |
| docs/content/docs/v5/migration-guides/{migrating-from-trigger-dev,migrating-from-temporal,migrating-from-inngest,migrating-from-aws-step-functions}.mdx | Update to v5 native workflow-context start(); only collect step retains "use step". |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
TooTallNate
reviewed
May 18, 2026
Member
TooTallNate
left a comment
TooTallNate
left a comment
There was a problem hiding this comment.
Comment-only review
The new versioning foundations page is a useful addition — the four sections (default pinning → recovery → self-upgrade via start({ deploymentId: "latest" }) → carrying serializable context forward) cover the model clearly, and the v4-vs-v5 differentiation (step-wrapped start() vs direct start() from workflow context, gated on whether PR #1491 has landed on the target branch) is correctly handled. The cross-links from cookbook patterns to the new foundations page tie everything together nicely.
Three observations — see inline.
Inline comments
- Wording: this PR introduces "Vercelism" as a new term and uses it 6 times across the diff, including replacing existing "Vercel-specific feature" wording in two
<Callout>s. "Vercelism" reads as informal slang and isn't part of the established docs vocabulary. The existing tone uses "Vercel-specific", "Vercel deployments", "Vercel World", "non-Vercel" — all precise. Suggested restoring the prior phrasing. This is the only thing I'd consider blocking. - Broken link in v4:
versioning.mdxreferences/docs/foundations/cancellationin itsrelatedfrontmatter, but that page is v5-only. Easy fix. - Missing changeset: convention for docs-only PRs is an empty
---\n---file.
A few small things I noticed
- The
pre-emptively check for a conflict with getHookByToken()example (line 96 ofversioning.mdx) — nice that you noted the race window in a later doc (#2011 callout), but this page doesn't have that warning. Worth a cross-link or<Callout type="warn">here too, since the recovery pattern uses bothstart()anddeploymentId: "latest"together. - The
_idempotency/usingsyntax is great. Worth confirming the docs site's syntax highlighter renders it — I noticed #1988 recently fixed a homepage link lint regression, and theusingsyntax is TypeScript 5.2+ specific. dailyDigestexample (line 137-152): thestateparameter isDigestStatebut the workflow doesn't actually usestate.userIdafter the firstsendDigestcall — pattern is fine, just noting if you wanted to make the example illustrate state evolution more vividly, havingsendDigestreadstate.lastSentAt(e.g. to avoid sending duplicates) would make the carry-forward intent clearer.
Overall the page reads well — once the Vercelism wording is restored and the v4 link is fixed, this should be good to go.
TooTallNate
approved these changes
May 18, 2026
Member
TooTallNate
left a comment
TooTallNate
left a comment
There was a problem hiding this comment.
All three review comments addressed in 7eff96c — Vercelism wording reverted, v4 broken cancellation link fixed, empty changeset added. LGTM, approving.
Contributor
|
Backport PR opened against |
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 free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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
Adds a new Foundations page explaining Workflow SDK versioning semantics for both v5 and v4 docs.
The page covers:
deploymentId: "latest"This also links existing versioning and
deploymentId: "latest"mentions back to the new Foundations page, and calls out thatdeploymentIdis currently a Vercelism that may become a more genericversionconcept in the World spec later.Follow-up cookbook pass added targeted callouts for long-lived or multi-turn patterns:
The docs now also distinguish v5 from v4 for child-run starts. Native
start()from workflow context was added bye295bae41/ #1491, which is onmainbut notstable, so v5 examples encourage direct workflow-contextstart()and v4 keeps the step-wrapped pattern.Validation
git diff --checkmeta.jsonfiles as JSONdocs/contentfor stale v5 step-wrappedstart()guidance and v4 direct-start guidanceorigin/stablelacks the'use step'directive inpackages/core/src/runtime/start.ts, whilemainhas it viae295bae41/ feat: allowstart()to be called directly inside workflow functions #1491Full docs lint/typecheck were not run because this checkout does not have
node_modulesinstalled, sobiome,vitest, andchangesetare unavailable locally.