[docs] Polish migration guides for scanability#1721
Open
johnlindquist wants to merge 7 commits intomainfrom
Open
[docs] Polish migration guides for scanability#1721johnlindquist wants to merge 7 commits intomainfrom
johnlindquist wants to merge 7 commits intomainfrom
Conversation
Tighten prose, break up code walls, and rework each migration guide (Temporal, Inngest, AWS Step Functions) to the house style. Imperative section headers, minimum-viable code samples that layer up, and a step-by-step first-migration walkthrough before the checklist.
Contributor
|
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro 10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro 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🌍 Community Worlds (74 failed)mongodb (7 failed):
redis (7 failed):
turso (60 failed):
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
❌ 🌍 Community Worlds
✅ 📋 Other
|
Verification pass across the three guides:
- Temporal: correct `startToCloseTimeout` duration string ('5 minute' → '5 minutes').
- Inngest: update `inngest.createFunction` to the current 2-arg form with
`triggers` inside the config, and add the required `timeout` option to the
`step.waitForEvent` Before example.
- AWS Step Functions: add missing `Resource: "arn:aws:states:::lambda:invoke"`
+ `Parameters` to the saga Task states so the ASL snippet is valid.
Workflow SDK snippets checked against node_modules/workflow/docs and
packages/core source; no changes needed.
Across all four migration guides, any code block that paired a source- system example with a Workflow SDK example via inline // Before / // After comments is now two adjacent fenced blocks, each with a descriptive title= attribute naming the source. Also applies trigger.dev verification fixes: remove the non-existent retry.exponentialBackoff helper from the guide's concept table and the skill reference, and tighten the refund Before snippet with token.id, .unwrap(), and a wait.completeToken example.
From Pranay's Slack review of PR #1721. Applied across all four guides (Temporal, Inngest, AWS Step Functions, trigger.dev): - Remove emdashes from intros and prose (AI-generated tell). - Fix install command: drop non-existent @workflow/next package; workflow/next is a subpath of the `workflow` package. - Rewrite saga sections. The rollback stack is a generic TypeScript compensation pattern, not an SDK feature. Dropped comparative framing that misrepresented how Temporal / Inngest / Step Functions / trigger.dev implement SAGA. - Recommend named streams (getWritable({ namespace: 'status' })) for read paths instead of database polling, getRun() polling, or app-layer caches. Clients read from the end of the stream for current status. - Return Run objects (not runId strings) from child-workflow step wrappers so workflow observability can deep-link into child runs. API-route HTTP handlers still return { runId } to external clients. - Add a "Why migrate to the Workflow SDK" section per guide, tailored to each source system's architecture. - Scrub vague "app API" / "app layer" references.
Remove the "Writing a saga" section from each migration guide (it described a generic TypeScript compensation pattern rather than an SDK feature) and surface the migration skill install command in a callout at the top of the index and each guide.
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
1 participant
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
Test plan
pnpm --filter docs dev) and confirm MDX renders, Callouts display, and syntax highlights match.relatedblock still resolve.