temporalio / temporalio/documentation

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

Open
#5,284 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
173
Forks
330
Avg merge
1d 20h
Merged PRs (30d)
156

Description

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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by grepping the listed documentation files for Workflow code and Workflow's code, then review each match against the determinism-claim guidance. Update only those terminology instances, inspect the advisory Vale rule if needed, and verify touched files with Vale and the full docs with yarn build; done means terminology is consistent without changing technical claims, examples, or structure.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, go, java, javascript, php, python, ruby, rust, typescript
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.