Skip to content

Replace "Workflow code" with "Workflow Definition" across baseline docs #5284

Description

@Duncanma

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions