temporalio / temporalio/documentation
Replace "Workflow code" with "Workflow Definition" across baseline docs
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 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 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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