Context
Follow-up to #5279, #5280, #5281, which scoped "Workflow" determinism language to "Workflow Definition" instead of the ambiguous "Workflow code."
Team feedback on those PRs: "Workflow code" is ambiguous because Activity code is also code that's part of a Workflow-based application, so it doesn't clearly exclude Activities the way we want. Temporal already has the precise, pre-existing, linkable term for exactly the thing that must be deterministic — Workflow Definition (the code the Worker replays), as distinct from Activity Definition. That's what should be used instead of "Workflow code" when a sentence asserts the determinism property.
| Level |
Deterministic? |
| Business process, end to end |
No |
| Workflow Definition — the code the Worker replays |
Yes |
| Activity code — API calls, database queries, LLM calls, file reads |
No |
Those 3 PRs fixed ~20 instances but deliberately left the pervasive baseline convention untouched, since fixing it was a substantially larger, separate effort from the original scoping sweep.
What needs fixing (~40 instances)
Apply the identical "Workflow code" → "Workflow Definition" swap (grammar adjusted per sentence — e.g. drop possessives like "Workflow's code" → "the Workflow Definition") across:
docs/encyclopedia/workflow/workflow-definition.mdx — the canonical "Deterministic constraints" section (#deterministic-constraints) has a tip box: "Workflow code must be deterministic to support replay..." right after a sentence that correctly says "developing Workflow Definitions is ensuring that they are deterministic." Fix the tip box and any other "Workflow code" instances in that section to match.
- All 7 SDKs'
docs/develop/<lang>/workflows/basics.mdx (go, java, python, typescript, dotnet, php, rust) — each has 1-3 "Workflow code must be deterministic..." mentions in the Workflow-constraints section.
- All 6 SDKs'
docs/develop/<lang>/workflows/versioning.mdx (go, java, dotnet, php, ruby, typescript) — each has a near-identical sentence: "The Temporal Platform requires that Workflow code is deterministic... This only applies to Workflow orchestration logic," plus 2-3 more "Workflow code" mentions and frontmatter description fields.
docs/develop/safe-deployments.mdx — opens with "Your Workflow code—as opposed to your Activity code—must be deterministic," plus ~5 more mentions throughout.
Scoping guidance
Grep each file for Workflow code and Workflow's code to find every instance, then judge case-by-case: only rewrite instances that assert the determinism property (the sentence claims something must/is/needs to be deterministic). Leave alone incidental mentions like "don't do I/O in Workflow code" or "changes to your Workflow code" that don't make a determinism claim — those are fine as general descriptive usage, same as elsewhere in the repo.
Also worth checking: whether vale/styles/Temporal/DeterminismScope.yml (an advisory-only Vale rule added in #5281) should gain new regex tokens to flag "Workflow code" + determinism-claim patterns now that the standard has shifted — but only if it can be done without false-positiving on the many legitimate "Workflow code" uses. If the false-positive rate is too high, leave the rule as-is; it already catches bare "Workflow is/are/must be deterministic" without "code"/"Definition"/"logic" in between, which remains valid regardless.
Verification
Run vale --config .vale-ci.ini docs/ on touched files and resolve anything it reports (except pre-existing heading-capitalization suggestions unrelated to these edits). Run yarn build to confirm no MDX breakage. This is purely a terminology/wording pass — no technical claims, code samples, or structure should change.
Context
Follow-up to #5279, #5280, #5281, which scoped "Workflow" determinism language to "Workflow Definition" instead of the ambiguous "Workflow code."
Team feedback on those PRs: "Workflow code" is ambiguous because Activity code is also code that's part of a Workflow-based application, so it doesn't clearly exclude Activities the way we want. Temporal already has the precise, pre-existing, linkable term for exactly the thing that must be deterministic — Workflow Definition (the code the Worker replays), as distinct from Activity Definition. That's what should be used instead of "Workflow code" when a sentence asserts the determinism property.
Those 3 PRs fixed ~20 instances but deliberately left the pervasive baseline convention untouched, since fixing it was a substantially larger, separate effort from the original scoping sweep.
What needs fixing (~40 instances)
Apply the identical "Workflow code" → "Workflow Definition" swap (grammar adjusted per sentence — e.g. drop possessives like "Workflow's code" → "the Workflow Definition") across:
docs/encyclopedia/workflow/workflow-definition.mdx— the canonical "Deterministic constraints" section (#deterministic-constraints) has a tip box: "Workflow code must be deterministic to support replay..." right after a sentence that correctly says "developing Workflow Definitions is ensuring that they are deterministic." Fix the tip box and any other "Workflow code" instances in that section to match.docs/develop/<lang>/workflows/basics.mdx(go, java, python, typescript, dotnet, php, rust) — each has 1-3 "Workflow code must be deterministic..." mentions in the Workflow-constraints section.docs/develop/<lang>/workflows/versioning.mdx(go, java, dotnet, php, ruby, typescript) — each has a near-identical sentence: "The Temporal Platform requires that Workflow code is deterministic... This only applies to Workflow orchestration logic," plus 2-3 more "Workflow code" mentions and frontmatterdescriptionfields.docs/develop/safe-deployments.mdx— opens with "Your Workflow code—as opposed to your Activity code—must be deterministic," plus ~5 more mentions throughout.Scoping guidance
Grep each file for
Workflow codeandWorkflow's codeto find every instance, then judge case-by-case: only rewrite instances that assert the determinism property (the sentence claims something must/is/needs to be deterministic). Leave alone incidental mentions like "don't do I/O in Workflow code" or "changes to your Workflow code" that don't make a determinism claim — those are fine as general descriptive usage, same as elsewhere in the repo.Also worth checking: whether
vale/styles/Temporal/DeterminismScope.yml(an advisory-only Vale rule added in #5281) should gain new regex tokens to flag "Workflow code" + determinism-claim patterns now that the standard has shifted — but only if it can be done without false-positiving on the many legitimate "Workflow code" uses. If the false-positive rate is too high, leave the rule as-is; it already catches bare "Workflow is/are/must be deterministic" without "code"/"Definition"/"logic" in between, which remains valid regardless.Verification
Run
vale --config .vale-ci.ini docs/on touched files and resolve anything it reports (except pre-existing heading-capitalization suggestions unrelated to these edits). Runyarn buildto confirm no MDX breakage. This is purely a terminology/wording pass — no technical claims, code samples, or structure should change.