Add missing cross-links and fix tone in the design-patterns catalog - #5254
Draft
Duncanma wants to merge 4 commits into
Draft
Add missing cross-links and fix tone in the design-patterns catalog#5254Duncanma wants to merge 4 commits into
Duncanma wants to merge 4 commits into
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.
Cross-links (from the Tier B review's "missing cross-links" list):
- best-practices/multi-tenant-patterns.mdx now links back to
design-patterns/fairness.mdx and priority-task-queues.mdx from its
"Single Task Queue with Fairness" section — the reverse direction
already existed (fairness.mdx links to multi-tenant-patterns.mdx)
but not this one.
- child-workflows.mdx -> /parent-close-policy and the four per-SDK
child-workflows how-to guides.
- signal-with-start.mdx, request-response-via-updates.mdx ->
/sending-messages and /handling-messages.
- pick-first.mdx -> /develop/go/workflows/selectors (same underlying
Go Selector construct, same sample repo).
- parallel-execution.mdx -> /troubleshooting/blob-size-limit-error and
/workflow-execution/limits.
- fixed-wall-time-retries.mdx -> /encyclopedia/detecting-activity-failures
(defines ScheduleToCloseTimeout/StartToCloseTimeout).
- fast-slow-retries.mdx, retry-metrics.mdx, resumable-activity.mdx ->
/encyclopedia/retry-policies, matching their sibling pages.
- activity-dependency-injection.mdx -> the Go/TypeScript Activity DI
how-tos and best-practices/worker.mdx.
- updatable-timer.mdx -> /develop/typescript/workflows/timers, which
documents the same UpdatableTimer class via the temporal-time-utils
package.
- long-running-activity.mdx, polling.mdx ->
/encyclopedia/detecting-activity-failures#activity-heartbeat.
- delayed-callback.mdx -> /activity-execution#asynchronous-activity-completion.
- delayed-start.mdx, continue-as-new.mdx -> /schedule, and linked the
existing unlinked "Temporal Schedules" bullet in delayed-start.mdx.
All new anchor links verified against the built HTML output directly
(yarn check-links flags them as "fragment-redirect" false positives —
it doesn't parse the unquoted id= attributes Docusaurus emits).
Tone fixes:
- resumable-activity.mdx and fast-slow-retries.mdx: removed a
narrative-climax line ("the Workflow never died") and a
self-congratulatory flourish ("exactly what a Temporal Workflow
is"), replaced with plain factual statements.
- downstream-rate-limiting.mdx: cut a Problem-section sentence that
only restated the one before it.
- worker-specific-taskqueue.mdx, activity-dependency-injection.mdx:
reformatted "When to use" (and, for the former, "Benefits and
trade-offs") from run-on sentences stacking 4-5 unrelated items into
bulleted Good-fit/Poor-fit lists, matching every sibling page's
template.
- continue-as-new.mdx, long-running-activity.mdx, entity-workflow.mdx,
polling.mdx, delayed-start.mdx, updatable-timer.mdx: rewrote the
templated "you often need X1, X2, X3, X4, and X5 ... without it you
must A1, A2, A3, and A4" Problem-section opener into plain prose,
preserving every fact.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
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 #5246 (Tier B). Remaining Tier B findings from the design-patterns review: the missing cross-links list and the tone findings.
Cross-links
best-practices/multi-tenant-patterns.mdxnow links back todesign-patterns/fairness.mdxandpriority-task-queues.mdxfrom its "Single Task Queue with Fairness" section — the reverse direction already existed (fairness.mdxlinks tomulti-tenant-patterns.mdx) but not this one.child-workflows.mdx→/parent-close-policyand the four per-SDK child-workflows how-to guides.signal-with-start.mdx,request-response-via-updates.mdx→/sending-messagesand/handling-messages.pick-first.mdx→/develop/go/workflows/selectors(same underlying GoSelectorconstruct, same sample repo).parallel-execution.mdx→/troubleshooting/blob-size-limit-errorand/workflow-execution/limits.fixed-wall-time-retries.mdx→/encyclopedia/detecting-activity-failures(definesScheduleToCloseTimeout/StartToCloseTimeout).fast-slow-retries.mdx,retry-metrics.mdx,resumable-activity.mdx→/encyclopedia/retry-policies, matching their sibling pages.activity-dependency-injection.mdx→ the Go/TypeScript Activity DI how-tos andbest-practices/worker.mdx.updatable-timer.mdx→/develop/typescript/workflows/timers, which documents the sameUpdatableTimerclass via thetemporal-time-utilspackage.long-running-activity.mdx,polling.mdx→/encyclopedia/detecting-activity-failures#activity-heartbeat.delayed-callback.mdx→/activity-execution#asynchronous-activity-completion.delayed-start.mdx,continue-as-new.mdx→/schedule, and linked the existing unlinked "Temporal Schedules" bullet indelayed-start.mdx.All new anchor links were verified against the built HTML output directly —
yarn check-linksflags them as "fragment-redirect" false positives, since it doesn't parse the unquotedid=attributes Docusaurus emits in minified HTML.Tone
resumable-activity.mdxandfast-slow-retries.mdx: removed a narrative-climax line ("the Workflow never died") and a self-congratulatory flourish ("exactly what a Temporal Workflow is"), replaced with plain factual statements.downstream-rate-limiting.mdx: cut a Problem-section sentence that only restated the one before it.worker-specific-taskqueue.mdx,activity-dependency-injection.mdx: reformatted "When to use" (and, for the former, "Benefits and trade-offs") from run-on sentences stacking 4-5 unrelated items into bulleted Good-fit/Poor-fit lists, matching every sibling page's template.continue-as-new.mdx,long-running-activity.mdx,entity-workflow.mdx,polling.mdx,delayed-start.mdx,updatable-timer.mdx: rewrote the templated "you often need X1, X2, X3, X4, and X5 ... without it you must A1, A2, A3, and A4" Problem-section opener into plain prose, preserving every fact.Test plan
vale --config .vale-ci.ini docs/clean on every touched fileyarn buildsucceeds#activity-heartbeat,#asynchronous-activity-completion, etc.) confirmed present in the built HTML