Document the Design Patterns section and fix technical inaccuracies - #5246
Merged
Conversation
- Add the missing Event Accumulator card to the design-patterns index (present in sidebars.js but absent from the landing page). - Rewrite 13 meta descriptions that fell outside the site's 120-155 character target, and sync the matching PatternCards blurbs on the top-level index and sub-category index pages so they don't drift from the frontmatter they were copied from. - Fix continue-as-new.mdx's "50,000 event history limit" to the documented 51,200 (docs/encyclopedia/workflow/workflow-execution/limits.mdx). - Remove a dangling "In the future - Org-to-Org Nexus, stay tuned" bullet from delayed-callback.mdx (future promise, no actual link).
- Add a "Design patterns" entry to readme/INFORMATION-ARCHITECTURE.md describing its audience, template, and how it differs from Guides and Best Practices. The section (added in #4746) had no IA entry. - Add frontmatter tags to all 46 pages in docs/design-patterns/, which had none (unlike ~90% of docs/ pages). Every page gets a shared "Design Patterns" tag; leaf pages also get one topic tag reused from the site's existing vocabulary (Activities, Workflows, Signals, Updates, Errors, Child Workflows, Task Queues, Workers, Timers, Metrics, Failures). - Cross-link docs/evaluate/use-cases-design-patterns.mdx (which predates this catalog) to the canonical Saga, Approval, and Long-Running Activity pattern pages it was duplicating without linking to.
All claims below verified against the temporalio/temporal, sdk-go, sdk-python, and sdk-typescript source on GitHub, not just against other doc pages. - eager-workflow-start.mdx claimed TypeScript doesn't support Eager Workflow Start. It does (WorkflowOptions.requestEagerStart, wired through NativeConnection and the gRPC start request in sdk-typescript) — added a TypeScript tab and corrected every claim that excluded it. Also added the missing .NET SDK (RequestEagerStart), and fixed the self-hosted guidance: system.enableEagerWorkflowStart defaults to true (confirmed in temporal's dynamicconfig/constants.go) rather than needing to be turned on, so the pitfall is an operator having disabled it, not one having forgotten to enable it. Cross-linked to the canonical /develop/worker-performance#eager-workflow-start page. - local-activities.mdx's timeout pitfall omitted Workflow Task heartbeating, the SDK's actual mitigation (sdk-go's ratioToForceCompleteWorkflowTaskComplete = 0.8, i.e. the ~80% figure the encyclopedia page already cites). Added it, plus the missing cross-link to /local-activity. - non-retryable-errors.mdx didn't mention that wrapping a non-retryable ApplicationFailure in a plain language error loses the flag. Confirmed in sdk-go: ErrorToFailure does a concrete type switch on the outermost error only, so a fmt.Errorf-wrapped ApplicationError falls through to a default retryable failure. - downstream-rate-limiting.mdx didn't mention that Eager Activity execution can bypass the rate-limited Task Queue. Added it, and confirmed the exact per-SDK difference: sdk-python requires disable_eager_activity_execution=True explicitly, while sdk-go's worker.go auto-disables eager activities whenever TaskQueueActivitiesPerSecond is set. - delayed-retry.mdx was missing the Python and Go tabs every sibling page has. Added them using the real ApplicationError/next_retry_delay (Python) and NewApplicationErrorWithOptions/NextRetryDelay (Go) APIs, matching this repo's own SDK reference pages. - docs/develop/worker-tuning-reference.mdx used MaxConcurrentActivityTaskExecutionSize / MaxConcurrentLocalActivityTaskExecutionSize. Neither field has "Task" in it in sdk-go, sdk-java, or sdk-typescript — fixed to MaxConcurrentActivityExecutionSize / MaxConcurrentLocalActivityExecutionSize. (The design-patterns page using these names was already correct.) - Reconciled the Child Workflow fan-out guidance: the encyclopedia's recommended cap of 1,000 Child Workflow Executions per parent wasn't surfaced in child-workflows.mdx, fanout-child-workflows.mdx, sliding-window.mdx, or mapreduce-tree.mdx, and batch-processing-patterns.mdx's "~4M records" Fan-Out capacity figure didn't account for it (it multiplied the hard 2,000-child limit by 2,000 activities/child instead). Added the 1,000 figure to all four pitfalls sections and revised the capacity estimate to ~500K, consistent with this page's own "aim for 500 Activities per child" guidance. Also fixed a "50,000 event history limit" mention in fanout-child-workflows.mdx to the documented 51,200.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| This page provides an overview of how leading organizations leverage Temporal to solve real-world problems, general use cases, and architectural design patterns. | ||
| This page provides an overview of how leading organizations leverage Temporal to solve real-world problems, general use cases, and architectural design patterns. For a full catalog of reusable, code-level Workflow and Activity patterns, see [Temporal Design Patterns](/design-patterns). | ||
|
|
||
| ## Use Cases of Temporal in Production |
Contributor
There was a problem hiding this comment.
📝 [vale] <Temporal.Headings> reported by reviewdog 🐶
'Use Cases of Temporal in Production' should use sentence-style capitalization.
|
|
||
| For a reusable implementation of this pattern, see [Approval](/design-patterns/approval). | ||
|
|
||
| ### Polyglot Systems |
Contributor
There was a problem hiding this comment.
📝 [vale] <Temporal.Headings> reported by reviewdog 🐶
'Polyglot Systems' should use sentence-style capitalization.
Contributor
4 tasks
…tier-b # Conflicts: # docs/design-patterns/delayed-callback.mdx # docs/design-patterns/delayed-retry.mdx # docs/design-patterns/downstream-rate-limiting.mdx # docs/design-patterns/eager-workflow-start.mdx # docs/design-patterns/early-return-local-activities.mdx # docs/design-patterns/entity-workflow.mdx # docs/design-patterns/external-interaction-patterns.mdx # docs/design-patterns/fast-slow-retries.mdx # docs/design-patterns/local-activities.mdx # docs/design-patterns/pick-first.mdx # docs/design-patterns/request-response-via-updates.mdx # docs/design-patterns/retry-metrics.mdx # docs/design-patterns/task-orchestration-patterns.mdx
Duncanma
marked this pull request as ready for review
September 10, 2026 22:08
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bc84f30656
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
The performance-latency-patterns.mdx selection guide still said Eager Workflow Start was limited to Go/Java/Python and told TypeScript users outright that it wasn't available - both wrong since eager-workflow-start.mdx was corrected to cover TypeScript and .NET. Update the comparison table's SDK Support column and drop the now-incorrect TypeScript-specific callout and "You are using TypeScript" branch, which steered TypeScript readers away from a pattern they can actually use. Flagged by chatgpt-codex-connector's review on #5246.
Contributor
Author
|
Addressed in efd8ab8: performance-latency-patterns.mdx's comparison table now lists TypeScript and .NET alongside Go/Java/Python for Eager Workflow Start, and I removed the TypeScript-specific callout and "You are using TypeScript" branch that told readers the pattern was unavailable there. The two Vale heading comments ( |
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
Stacked on #5245 (Tier A). Tier B (judgment-call) findings from a full review of
docs/design-patterns/, split into two commits:Structural / IA placement
docs/design-patterns/, which had none (unlike ~90% ofdocs/pages). Every page gets a sharedDesign Patternstag; leaf pages also get one topic tag reused from the site's existing vocabulary.Technical inaccuracies — each verified against actual SDK/server source on GitHub (temporalio/temporal, sdk-go, sdk-python, sdk-typescript), not just against other doc pages:
eager-workflow-start.mdxclaimed TypeScript doesn't support Eager Workflow Start. It does (WorkflowOptions.requestEagerStart, wired throughNativeConnectionin sdk-typescript) — added a TypeScript tab and corrected every claim that excluded it. Also added .NET (RequestEagerStart), and fixed the self-hosted guidance:system.enableEagerWorkflowStartdefaults totrue(confirmed in temporal'sdynamicconfig/constants.go) rather than needing to be turned on.local-activities.mdx's timeout pitfall omitted Workflow Task heartbeating, the SDK's actual mitigation (sdk-go'sratioToForceCompleteWorkflowTaskComplete = 0.8, matching the ~80% figure the encyclopedia page already cites).non-retryable-errors.mdxdidn't mention that wrapping a non-retryableApplicationFailurein a plain language error loses the flag — confirmed in sdk-go'sErrorToFailure, which type-switches on the outermost error only.downstream-rate-limiting.mdxdidn't mention Eager Activity execution bypassing the rate-limited Task Queue, and the exact per-SDK difference (Python needsdisable_eager_activity_execution=Trueexplicitly; Go auto-disables it whenTaskQueueActivitiesPerSecondis set).delayed-retry.mdxwas missing the Python and Go tabs every sibling page has — added using the realApplicationError/next_retry_delay(Python) andNewApplicationErrorWithOptions/NextRetryDelay(Go) APIs.docs/develop/worker-tuning-reference.mdxusedMaxConcurrentActivityTaskExecutionSize/MaxConcurrentLocalActivityTaskExecutionSize. Neither field has "Task" in it in sdk-go, sdk-java, or sdk-typescript — fixed.batch-processing-patterns.mdx's "~4M records" Fan-Out capacity figure didn't account for it. Also fixed a "50,000 event history limit" mention to the documented 51,200.Test plan
vale --config .vale-ci.ini docs/clean on every touched fileyarn buildsucceedsDesign Patternstag before merge