docs(cookbook): add Upgrading Workflows guide

[karthikscale3]

Summary

Adds a new advanced cookbook page — /cookbook/advanced/upgrading-workflows — for handling long-running workflows that need to pick up shipped fixes without migrating in-flight runs.

The guide is built around a single principle: identify a clean upgrade point in the workflow (a moment where state can be checkpointed and a new run started fresh) and call start() with deploymentId: "latest" to hand off to whatever deployment is current.

It documents two methods:

• Method 1 — Upgrade on every iteration. Each run handles one event, then unconditionally spawns its successor on the latest deployment before exiting. Best for short, frequent iterations where you want shipped fixes to apply on the very next event.
• Method 2 — Upgrade on demand via a dedicated hook. A long-lived run handles events in a loop and races the work hook against an upgradeHook. A separate endpoint resumes the upgrade hook (e.g. from a control plane after a deploy), at which point the workflow checkpoints state and respawns on the latest deployment. Best when iterations are infrequent/expensive or when "upgrade" should be an explicit operation that can be fanned out across a fleet.

Both methods share the same "How it works" section (the deploymentId: "latest" knob, start() from a step, state-via-argument, per-run hook tokens) and Caveats (backward-compat constraints, stable workflow identity, hook-not-found gap between iterations, plus a Method-2-specific note on tracking active runs).

Files changed

• docs/content/docs/cookbook/advanced/upgrading-workflows.mdx — new guide
• docs/content/docs/cookbook/advanced/meta.json — adds the slug to the Advanced section
• docs/lib/cookbook-tree.ts — adds the page to the cookbook sidebar (slug → category map and recipes entry)
• docs/content/docs/cookbook/index.mdx — adds a link from the cookbook landing page

Test plan

• pnpm dev (docs) and visit /cookbook/advanced/upgrading-workflows — page renders with both Method 1 and Method 2 sections, anchor links work
• Sidebar under "Advanced" shows "Upgrading Workflows" between Distributed Abort Controller and Serializable Steps
• Cookbook landing page (/cookbook) lists "Upgrading Workflows" under Advanced
• Code blocks in both methods compile cleanly against the workflow SDK types (TypeScript)
• No build/MDX errors in the docs dev server output

Made with Cursor

[VaguelySerious]

AI review: no blocking issues

Polished the PR on top of the original commit:

• Ported the page to the v5 content tree (direct workflow-context start() per #1491; v4 keeps the step-wrapped pattern as written)
• Cross-linked to /docs/foundations/versioning (added in #2010 since this PR was opened) — Method 1 here is the hook-driven analog of versioning.mdx's sleep-based "Self upgrading workflows"; Method 2 (dedicated upgradeHook) is fully unique
• Registered the page in the v5 cookbook sidebar (meta.json) and landing index
• Added an empty changeset

Verified both /cookbook/advanced/upgrading-workflows (v4) and /v5/cookbook/advanced/upgrading-workflows render with all sections in a local dev server. Docs CI checks (Docs Code Samples, Docs Links, Docs Preview Smoke Checks, Tarballs Preview Smoke Checks) all green.

[github-actions]

No backport to stable for c502364 (AI decision).

The substantive content of this commit is a new cookbook guide added under docs/content/docs/v4/cookbook/ and docs/content/docs/v5/cookbook/, plus an entry in docs/lib/cookbook-tree.ts — but the stable branch has no v4/v5 versioned docs structure and no cookbook/ directory at all under docs/content/docs/, and docs/lib/ is part of the unmaintained docs app. The only other change is a trivial whitespace reformat in packages/world-local/src/queue.test.ts (line-wrapping a single statement) which isn't worth a standalone backport.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c5023646d16c68fabab9ef258144a8eb283c3a66

[karthikscale3]

Summary

Adds a new advanced cookbook page — /cookbook/advanced/upgrading-workflows — for handling long-running workflows that need to pick up shipped fixes without migrating in-flight runs.

The guide is built around a single principle: identify a clean upgrade point in the workflow (a moment where state can be checkpointed and a new run started fresh) and call start() with deploymentId: "latest" to hand off to whatever deployment is current.

It documents two methods:

• Method 1 — Upgrade on every iteration. Each run handles one event, then unconditionally spawns its successor on the latest deployment before exiting. Best for short, frequent iterations where you want shipped fixes to apply on the very next event.
• Method 2 — Upgrade on demand via a dedicated hook. A long-lived run handles events in a loop and races the work hook against an upgradeHook. A separate endpoint resumes the upgrade hook (e.g. from a control plane after a deploy), at which point the workflow checkpoints state and respawns on the latest deployment. Best when iterations are infrequent/expensive or when "upgrade" should be an explicit operation that can be fanned out across a fleet.

Both methods share the same "How it works" section (the deploymentId: "latest" knob, start() from a step, state-via-argument, per-run hook tokens) and Caveats (backward-compat constraints, stable workflow identity, hook-not-found gap between iterations, plus a Method-2-specific note on tracking active runs).

Files changed

• docs/content/docs/cookbook/advanced/upgrading-workflows.mdx — new guide
• docs/content/docs/cookbook/advanced/meta.json — adds the slug to the Advanced section
• docs/lib/cookbook-tree.ts — adds the page to the cookbook sidebar (slug → category map and recipes entry)
• docs/content/docs/cookbook/index.mdx — adds a link from the cookbook landing page

Test plan

• pnpm dev (docs) and visit /cookbook/advanced/upgrading-workflows — page renders with both Method 1 and Method 2 sections, anchor links work
• Sidebar under "Advanced" shows "Upgrading Workflows" between Distributed Abort Controller and Serializable Steps
• Cookbook landing page (/cookbook) lists "Upgrading Workflows" under Advanced
• Code blocks in both methods compile cleanly against the workflow SDK types (TypeScript)
• No build/MDX errors in the docs dev server output

Made with Cursor

[VaguelySerious]

AI review: no blocking issues

Polished the PR on top of the original commit:

• Ported the page to the v5 content tree (direct workflow-context start() per #1491; v4 keeps the step-wrapped pattern as written)
• Cross-linked to /docs/foundations/versioning (added in #2010 since this PR was opened) — Method 1 here is the hook-driven analog of versioning.mdx's sleep-based "Self upgrading workflows"; Method 2 (dedicated upgradeHook) is fully unique
• Registered the page in the v5 cookbook sidebar (meta.json) and landing index
• Added an empty changeset

Verified both /cookbook/advanced/upgrading-workflows (v4) and /v5/cookbook/advanced/upgrading-workflows render with all sections in a local dev server. Docs CI checks (Docs Code Samples, Docs Links, Docs Preview Smoke Checks, Tarballs Preview Smoke Checks) all green.

[github-actions]

No backport to stable for c502364 (AI decision).

The substantive content of this commit is a new cookbook guide added under docs/content/docs/v4/cookbook/ and docs/content/docs/v5/cookbook/, plus an entry in docs/lib/cookbook-tree.ts — but the stable branch has no v4/v5 versioned docs structure and no cookbook/ directory at all under docs/content/docs/, and docs/lib/ is part of the unmaintained docs app. The only other change is a trivial whitespace reformat in packages/world-local/src/queue.test.ts (line-wrapping a single statement) which isn't worth a standalone backport.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c5023646d16c68fabab9ef258144a8eb283c3a66

[karthikscale3]

Summary

Adds a new advanced cookbook page — /cookbook/advanced/upgrading-workflows — for handling long-running workflows that need to pick up shipped fixes without migrating in-flight runs.

The guide is built around a single principle: identify a clean upgrade point in the workflow (a moment where state can be checkpointed and a new run started fresh) and call start() with deploymentId: "latest" to hand off to whatever deployment is current.

It documents two methods:

• Method 1 — Upgrade on every iteration. Each run handles one event, then unconditionally spawns its successor on the latest deployment before exiting. Best for short, frequent iterations where you want shipped fixes to apply on the very next event.
• Method 2 — Upgrade on demand via a dedicated hook. A long-lived run handles events in a loop and races the work hook against an upgradeHook. A separate endpoint resumes the upgrade hook (e.g. from a control plane after a deploy), at which point the workflow checkpoints state and respawns on the latest deployment. Best when iterations are infrequent/expensive or when "upgrade" should be an explicit operation that can be fanned out across a fleet.

Both methods share the same "How it works" section (the deploymentId: "latest" knob, start() from a step, state-via-argument, per-run hook tokens) and Caveats (backward-compat constraints, stable workflow identity, hook-not-found gap between iterations, plus a Method-2-specific note on tracking active runs).

Files changed

• docs/content/docs/cookbook/advanced/upgrading-workflows.mdx — new guide
• docs/content/docs/cookbook/advanced/meta.json — adds the slug to the Advanced section
• docs/lib/cookbook-tree.ts — adds the page to the cookbook sidebar (slug → category map and recipes entry)
• docs/content/docs/cookbook/index.mdx — adds a link from the cookbook landing page

Test plan

• pnpm dev (docs) and visit /cookbook/advanced/upgrading-workflows — page renders with both Method 1 and Method 2 sections, anchor links work
• Sidebar under "Advanced" shows "Upgrading Workflows" between Distributed Abort Controller and Serializable Steps
• Cookbook landing page (/cookbook) lists "Upgrading Workflows" under Advanced
• Code blocks in both methods compile cleanly against the workflow SDK types (TypeScript)
• No build/MDX errors in the docs dev server output

Made with Cursor

[VaguelySerious]

AI review: no blocking issues

Polished the PR on top of the original commit:

• Ported the page to the v5 content tree (direct workflow-context start() per #1491; v4 keeps the step-wrapped pattern as written)
• Cross-linked to /docs/foundations/versioning (added in #2010 since this PR was opened) — Method 1 here is the hook-driven analog of versioning.mdx's sleep-based "Self upgrading workflows"; Method 2 (dedicated upgradeHook) is fully unique
• Registered the page in the v5 cookbook sidebar (meta.json) and landing index
• Added an empty changeset

Verified both /cookbook/advanced/upgrading-workflows (v4) and /v5/cookbook/advanced/upgrading-workflows render with all sections in a local dev server. Docs CI checks (Docs Code Samples, Docs Links, Docs Preview Smoke Checks, Tarballs Preview Smoke Checks) all green.

[github-actions]

No backport to stable for c502364 (AI decision).

The substantive content of this commit is a new cookbook guide added under docs/content/docs/v4/cookbook/ and docs/content/docs/v5/cookbook/, plus an entry in docs/lib/cookbook-tree.ts — but the stable branch has no v4/v5 versioned docs structure and no cookbook/ directory at all under docs/content/docs/, and docs/lib/ is part of the unmaintained docs app. The only other change is a trivial whitespace reformat in packages/world-local/src/queue.test.ts (line-wrapping a single statement) which isn't worth a standalone backport.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c5023646d16c68fabab9ef258144a8eb283c3a66

[karthikscale3]

Summary

Adds a new advanced cookbook page — /cookbook/advanced/upgrading-workflows — for handling long-running workflows that need to pick up shipped fixes without migrating in-flight runs.

The guide is built around a single principle: identify a clean upgrade point in the workflow (a moment where state can be checkpointed and a new run started fresh) and call start() with deploymentId: "latest" to hand off to whatever deployment is current.

It documents two methods:

• Method 1 — Upgrade on every iteration. Each run handles one event, then unconditionally spawns its successor on the latest deployment before exiting. Best for short, frequent iterations where you want shipped fixes to apply on the very next event.
• Method 2 — Upgrade on demand via a dedicated hook. A long-lived run handles events in a loop and races the work hook against an upgradeHook. A separate endpoint resumes the upgrade hook (e.g. from a control plane after a deploy), at which point the workflow checkpoints state and respawns on the latest deployment. Best when iterations are infrequent/expensive or when "upgrade" should be an explicit operation that can be fanned out across a fleet.

Both methods share the same "How it works" section (the deploymentId: "latest" knob, start() from a step, state-via-argument, per-run hook tokens) and Caveats (backward-compat constraints, stable workflow identity, hook-not-found gap between iterations, plus a Method-2-specific note on tracking active runs).

Files changed

• docs/content/docs/cookbook/advanced/upgrading-workflows.mdx — new guide
• docs/content/docs/cookbook/advanced/meta.json — adds the slug to the Advanced section
• docs/lib/cookbook-tree.ts — adds the page to the cookbook sidebar (slug → category map and recipes entry)
• docs/content/docs/cookbook/index.mdx — adds a link from the cookbook landing page

Test plan

• pnpm dev (docs) and visit /cookbook/advanced/upgrading-workflows — page renders with both Method 1 and Method 2 sections, anchor links work
• Sidebar under "Advanced" shows "Upgrading Workflows" between Distributed Abort Controller and Serializable Steps
• Cookbook landing page (/cookbook) lists "Upgrading Workflows" under Advanced
• Code blocks in both methods compile cleanly against the workflow SDK types (TypeScript)
• No build/MDX errors in the docs dev server output

Made with Cursor

[VaguelySerious]

AI review: no blocking issues

Polished the PR on top of the original commit:

• Ported the page to the v5 content tree (direct workflow-context start() per #1491; v4 keeps the step-wrapped pattern as written)
• Cross-linked to /docs/foundations/versioning (added in #2010 since this PR was opened) — Method 1 here is the hook-driven analog of versioning.mdx's sleep-based "Self upgrading workflows"; Method 2 (dedicated upgradeHook) is fully unique
• Registered the page in the v5 cookbook sidebar (meta.json) and landing index
• Added an empty changeset

Verified both /cookbook/advanced/upgrading-workflows (v4) and /v5/cookbook/advanced/upgrading-workflows render with all sections in a local dev server. Docs CI checks (Docs Code Samples, Docs Links, Docs Preview Smoke Checks, Tarballs Preview Smoke Checks) all green.

[github-actions]

No backport to stable for c502364 (AI decision).

The substantive content of this commit is a new cookbook guide added under docs/content/docs/v4/cookbook/ and docs/content/docs/v5/cookbook/, plus an entry in docs/lib/cookbook-tree.ts — but the stable branch has no v4/v5 versioned docs structure and no cookbook/ directory at all under docs/content/docs/, and docs/lib/ is part of the unmaintained docs app. The only other change is a trivial whitespace reformat in packages/world-local/src/queue.test.ts (line-wrapping a single statement) which isn't worth a standalone backport.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c5023646d16c68fabab9ef258144a8eb283c3a66

[karthikscale3]

Summary

Adds a new advanced cookbook page — /cookbook/advanced/upgrading-workflows — for handling long-running workflows that need to pick up shipped fixes without migrating in-flight runs.

The guide is built around a single principle: identify a clean upgrade point in the workflow (a moment where state can be checkpointed and a new run started fresh) and call start() with deploymentId: "latest" to hand off to whatever deployment is current.

It documents two methods:

• Method 1 — Upgrade on every iteration. Each run handles one event, then unconditionally spawns its successor on the latest deployment before exiting. Best for short, frequent iterations where you want shipped fixes to apply on the very next event.
• Method 2 — Upgrade on demand via a dedicated hook. A long-lived run handles events in a loop and races the work hook against an upgradeHook. A separate endpoint resumes the upgrade hook (e.g. from a control plane after a deploy), at which point the workflow checkpoints state and respawns on the latest deployment. Best when iterations are infrequent/expensive or when "upgrade" should be an explicit operation that can be fanned out across a fleet.

Both methods share the same "How it works" section (the deploymentId: "latest" knob, start() from a step, state-via-argument, per-run hook tokens) and Caveats (backward-compat constraints, stable workflow identity, hook-not-found gap between iterations, plus a Method-2-specific note on tracking active runs).

Files changed

• docs/content/docs/cookbook/advanced/upgrading-workflows.mdx — new guide
• docs/content/docs/cookbook/advanced/meta.json — adds the slug to the Advanced section
• docs/lib/cookbook-tree.ts — adds the page to the cookbook sidebar (slug → category map and recipes entry)
• docs/content/docs/cookbook/index.mdx — adds a link from the cookbook landing page

Test plan

• pnpm dev (docs) and visit /cookbook/advanced/upgrading-workflows — page renders with both Method 1 and Method 2 sections, anchor links work
• Sidebar under "Advanced" shows "Upgrading Workflows" between Distributed Abort Controller and Serializable Steps
• Cookbook landing page (/cookbook) lists "Upgrading Workflows" under Advanced
• Code blocks in both methods compile cleanly against the workflow SDK types (TypeScript)
• No build/MDX errors in the docs dev server output

Made with Cursor

[VaguelySerious]

AI review: no blocking issues

Polished the PR on top of the original commit:

• Ported the page to the v5 content tree (direct workflow-context start() per #1491; v4 keeps the step-wrapped pattern as written)
• Cross-linked to /docs/foundations/versioning (added in #2010 since this PR was opened) — Method 1 here is the hook-driven analog of versioning.mdx's sleep-based "Self upgrading workflows"; Method 2 (dedicated upgradeHook) is fully unique
• Registered the page in the v5 cookbook sidebar (meta.json) and landing index
• Added an empty changeset

Verified both /cookbook/advanced/upgrading-workflows (v4) and /v5/cookbook/advanced/upgrading-workflows render with all sections in a local dev server. Docs CI checks (Docs Code Samples, Docs Links, Docs Preview Smoke Checks, Tarballs Preview Smoke Checks) all green.

[github-actions]

No backport to stable for c502364 (AI decision).

The substantive content of this commit is a new cookbook guide added under docs/content/docs/v4/cookbook/ and docs/content/docs/v5/cookbook/, plus an entry in docs/lib/cookbook-tree.ts — but the stable branch has no v4/v5 versioned docs structure and no cookbook/ directory at all under docs/content/docs/, and docs/lib/ is part of the unmaintained docs app. The only other change is a trivial whitespace reformat in packages/world-local/src/queue.test.ts (line-wrapping a single statement) which isn't worth a standalone backport.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c5023646d16c68fabab9ef258144a8eb283c3a66

[karthikscale3]

Summary

Adds a new advanced cookbook page — /cookbook/advanced/upgrading-workflows — for handling long-running workflows that need to pick up shipped fixes without migrating in-flight runs.

The guide is built around a single principle: identify a clean upgrade point in the workflow (a moment where state can be checkpointed and a new run started fresh) and call start() with deploymentId: "latest" to hand off to whatever deployment is current.

It documents two methods:

• Method 1 — Upgrade on every iteration. Each run handles one event, then unconditionally spawns its successor on the latest deployment before exiting. Best for short, frequent iterations where you want shipped fixes to apply on the very next event.
• Method 2 — Upgrade on demand via a dedicated hook. A long-lived run handles events in a loop and races the work hook against an upgradeHook. A separate endpoint resumes the upgrade hook (e.g. from a control plane after a deploy), at which point the workflow checkpoints state and respawns on the latest deployment. Best when iterations are infrequent/expensive or when "upgrade" should be an explicit operation that can be fanned out across a fleet.

Both methods share the same "How it works" section (the deploymentId: "latest" knob, start() from a step, state-via-argument, per-run hook tokens) and Caveats (backward-compat constraints, stable workflow identity, hook-not-found gap between iterations, plus a Method-2-specific note on tracking active runs).

Files changed

• docs/content/docs/cookbook/advanced/upgrading-workflows.mdx — new guide
• docs/content/docs/cookbook/advanced/meta.json — adds the slug to the Advanced section
• docs/lib/cookbook-tree.ts — adds the page to the cookbook sidebar (slug → category map and recipes entry)
• docs/content/docs/cookbook/index.mdx — adds a link from the cookbook landing page

Test plan

• pnpm dev (docs) and visit /cookbook/advanced/upgrading-workflows — page renders with both Method 1 and Method 2 sections, anchor links work
• Sidebar under "Advanced" shows "Upgrading Workflows" between Distributed Abort Controller and Serializable Steps
• Cookbook landing page (/cookbook) lists "Upgrading Workflows" under Advanced
• Code blocks in both methods compile cleanly against the workflow SDK types (TypeScript)
• No build/MDX errors in the docs dev server output

Made with Cursor

[VaguelySerious]

AI review: no blocking issues

Polished the PR on top of the original commit:

• Ported the page to the v5 content tree (direct workflow-context start() per #1491; v4 keeps the step-wrapped pattern as written)
• Cross-linked to /docs/foundations/versioning (added in #2010 since this PR was opened) — Method 1 here is the hook-driven analog of versioning.mdx's sleep-based "Self upgrading workflows"; Method 2 (dedicated upgradeHook) is fully unique
• Registered the page in the v5 cookbook sidebar (meta.json) and landing index
• Added an empty changeset

Verified both /cookbook/advanced/upgrading-workflows (v4) and /v5/cookbook/advanced/upgrading-workflows render with all sections in a local dev server. Docs CI checks (Docs Code Samples, Docs Links, Docs Preview Smoke Checks, Tarballs Preview Smoke Checks) all green.

[github-actions]

No backport to stable for c502364 (AI decision).

The substantive content of this commit is a new cookbook guide added under docs/content/docs/v4/cookbook/ and docs/content/docs/v5/cookbook/, plus an entry in docs/lib/cookbook-tree.ts — but the stable branch has no v4/v5 versioned docs structure and no cookbook/ directory at all under docs/content/docs/, and docs/lib/ is part of the unmaintained docs app. The only other change is a trivial whitespace reformat in packages/world-local/src/queue.test.ts (line-wrapping a single statement) which isn't worth a standalone backport.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c5023646d16c68fabab9ef258144a8eb283c3a66

[karthikscale3]

Summary

Adds a new advanced cookbook page — /cookbook/advanced/upgrading-workflows — for handling long-running workflows that need to pick up shipped fixes without migrating in-flight runs.

The guide is built around a single principle: identify a clean upgrade point in the workflow (a moment where state can be checkpointed and a new run started fresh) and call start() with deploymentId: "latest" to hand off to whatever deployment is current.

It documents two methods:

• Method 1 — Upgrade on every iteration. Each run handles one event, then unconditionally spawns its successor on the latest deployment before exiting. Best for short, frequent iterations where you want shipped fixes to apply on the very next event.
• Method 2 — Upgrade on demand via a dedicated hook. A long-lived run handles events in a loop and races the work hook against an upgradeHook. A separate endpoint resumes the upgrade hook (e.g. from a control plane after a deploy), at which point the workflow checkpoints state and respawns on the latest deployment. Best when iterations are infrequent/expensive or when "upgrade" should be an explicit operation that can be fanned out across a fleet.

Both methods share the same "How it works" section (the deploymentId: "latest" knob, start() from a step, state-via-argument, per-run hook tokens) and Caveats (backward-compat constraints, stable workflow identity, hook-not-found gap between iterations, plus a Method-2-specific note on tracking active runs).

Files changed

• docs/content/docs/cookbook/advanced/upgrading-workflows.mdx — new guide
• docs/content/docs/cookbook/advanced/meta.json — adds the slug to the Advanced section
• docs/lib/cookbook-tree.ts — adds the page to the cookbook sidebar (slug → category map and recipes entry)
• docs/content/docs/cookbook/index.mdx — adds a link from the cookbook landing page

Test plan

• pnpm dev (docs) and visit /cookbook/advanced/upgrading-workflows — page renders with both Method 1 and Method 2 sections, anchor links work
• Sidebar under "Advanced" shows "Upgrading Workflows" between Distributed Abort Controller and Serializable Steps
• Cookbook landing page (/cookbook) lists "Upgrading Workflows" under Advanced
• Code blocks in both methods compile cleanly against the workflow SDK types (TypeScript)
• No build/MDX errors in the docs dev server output

Made with Cursor

[VaguelySerious]

AI review: no blocking issues

Polished the PR on top of the original commit:

• Ported the page to the v5 content tree (direct workflow-context start() per #1491; v4 keeps the step-wrapped pattern as written)
• Cross-linked to /docs/foundations/versioning (added in #2010 since this PR was opened) — Method 1 here is the hook-driven analog of versioning.mdx's sleep-based "Self upgrading workflows"; Method 2 (dedicated upgradeHook) is fully unique
• Registered the page in the v5 cookbook sidebar (meta.json) and landing index
• Added an empty changeset

Verified both /cookbook/advanced/upgrading-workflows (v4) and /v5/cookbook/advanced/upgrading-workflows render with all sections in a local dev server. Docs CI checks (Docs Code Samples, Docs Links, Docs Preview Smoke Checks, Tarballs Preview Smoke Checks) all green.

[github-actions]

No backport to stable for c502364 (AI decision).

The substantive content of this commit is a new cookbook guide added under docs/content/docs/v4/cookbook/ and docs/content/docs/v5/cookbook/, plus an entry in docs/lib/cookbook-tree.ts — but the stable branch has no v4/v5 versioned docs structure and no cookbook/ directory at all under docs/content/docs/, and docs/lib/ is part of the unmaintained docs app. The only other change is a trivial whitespace reformat in packages/world-local/src/queue.test.ts (line-wrapping a single statement) which isn't worth a standalone backport.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c5023646d16c68fabab9ef258144a8eb283c3a66

[karthikscale3]

Summary

Adds a new advanced cookbook page — /cookbook/advanced/upgrading-workflows — for handling long-running workflows that need to pick up shipped fixes without migrating in-flight runs.

The guide is built around a single principle: identify a clean upgrade point in the workflow (a moment where state can be checkpointed and a new run started fresh) and call start() with deploymentId: "latest" to hand off to whatever deployment is current.

It documents two methods:

• Method 1 — Upgrade on every iteration. Each run handles one event, then unconditionally spawns its successor on the latest deployment before exiting. Best for short, frequent iterations where you want shipped fixes to apply on the very next event.
• Method 2 — Upgrade on demand via a dedicated hook. A long-lived run handles events in a loop and races the work hook against an upgradeHook. A separate endpoint resumes the upgrade hook (e.g. from a control plane after a deploy), at which point the workflow checkpoints state and respawns on the latest deployment. Best when iterations are infrequent/expensive or when "upgrade" should be an explicit operation that can be fanned out across a fleet.

Both methods share the same "How it works" section (the deploymentId: "latest" knob, start() from a step, state-via-argument, per-run hook tokens) and Caveats (backward-compat constraints, stable workflow identity, hook-not-found gap between iterations, plus a Method-2-specific note on tracking active runs).

Files changed

• docs/content/docs/cookbook/advanced/upgrading-workflows.mdx — new guide
• docs/content/docs/cookbook/advanced/meta.json — adds the slug to the Advanced section
• docs/lib/cookbook-tree.ts — adds the page to the cookbook sidebar (slug → category map and recipes entry)
• docs/content/docs/cookbook/index.mdx — adds a link from the cookbook landing page

Test plan

• pnpm dev (docs) and visit /cookbook/advanced/upgrading-workflows — page renders with both Method 1 and Method 2 sections, anchor links work
• Sidebar under "Advanced" shows "Upgrading Workflows" between Distributed Abort Controller and Serializable Steps
• Cookbook landing page (/cookbook) lists "Upgrading Workflows" under Advanced
• Code blocks in both methods compile cleanly against the workflow SDK types (TypeScript)
• No build/MDX errors in the docs dev server output

Made with Cursor

[VaguelySerious]

AI review: no blocking issues

Polished the PR on top of the original commit:

• Ported the page to the v5 content tree (direct workflow-context start() per #1491; v4 keeps the step-wrapped pattern as written)
• Cross-linked to /docs/foundations/versioning (added in #2010 since this PR was opened) — Method 1 here is the hook-driven analog of versioning.mdx's sleep-based "Self upgrading workflows"; Method 2 (dedicated upgradeHook) is fully unique
• Registered the page in the v5 cookbook sidebar (meta.json) and landing index
• Added an empty changeset

Verified both /cookbook/advanced/upgrading-workflows (v4) and /v5/cookbook/advanced/upgrading-workflows render with all sections in a local dev server. Docs CI checks (Docs Code Samples, Docs Links, Docs Preview Smoke Checks, Tarballs Preview Smoke Checks) all green.

[github-actions]

No backport to stable for c502364 (AI decision).

The substantive content of this commit is a new cookbook guide added under docs/content/docs/v4/cookbook/ and docs/content/docs/v5/cookbook/, plus an entry in docs/lib/cookbook-tree.ts — but the stable branch has no v4/v5 versioned docs structure and no cookbook/ directory at all under docs/content/docs/, and docs/lib/ is part of the unmaintained docs app. The only other change is a trivial whitespace reformat in packages/world-local/src/queue.test.ts (line-wrapping a single statement) which isn't worth a standalone backport.

To override, re-run the Backport to stable workflow manually via workflow_dispatch and paste this commit SHA into the ref input:

c5023646d16c68fabab9ef258144a8eb283c3a66