Skip to content

clarify Activity timeout defaults and normalization rules - #5490

Open
jsundai wants to merge 7 commits into
mainfrom
activity-timeout-normalization
Open

jsundai wants to merge 7 commits into
mainfrom
activity-timeout-normalization

Conversation

@jsundai

@jsundai jsundai commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

Closes #5267.

Two stated Activity timeout defaults were wrong. Schedule-To-Start and Schedule-To-Close
were both documented as defaulting to infinity. Neither has a default and the Temporal
Service derives them when it schedules the Activity.

  • Corrects both claims, plus adds the undocumented case where setting both
    Schedule-To-Close and a longer Start-To-Close silently stores the shorter value.
  • Adds a section to the Activity failures page with the five resolution rules in the
    order the Service applies them.
  • Documents the Update Options field mask on the Update Options page: named fields are
    assigned, omitted fields are untouched, and a field named with an empty value is
    cleared. The timeout rules then re-run over the merged result.
  • Adds one link to each of the eight SDK timeouts pages instead of duplicating the rules.

Notes to reviewers

@vercel

vercel Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
temporal-documentation Ready Ready Preview Nov 18, 2026 6:52pm UTC

Request Review

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

📖 Docs PR preview links

@jsundai
jsundai marked this pull request as ready for review November 17, 2026 16:25
@jsundai
jsundai requested a review from a team as a code owner November 17, 2026 16:25
Copilot AI balanced review requested due to automatic review settings November 17, 2026 16:25

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The documentation still gives conflicting guidance on timeout updates, omitted CLI flags, and how the Workflow Run Timeout cap applies to explicit values.

3 open issues
What changed in this PR

Clarifies Activity timeout defaults and normalization across the reference and SDK documentation, addressing #5267.

Changes:

  • Replaces infinite-default claims with timeout derivation and capping rules.
  • Explains Update Options field-mask behavior and timeout resolution after updates.
  • Links eight SDK pages to the shared rules and corrects a PHP timeout link.
File Description
docs/​evaluate/​features/​timeouts-and-retries.mdx Updates default descriptions and links to resolution rules.
docs/​encyclopedia/​detecting-activity-failures.mdx Adds scheduling-time resolution rules and examples.
docs/​encyclopedia/​activities/​activity-operations/​update-options.mdx Explains field masks, clearing, and update-time resolution.
docs/​develop/​typescript/​activities/​timeouts.mdx Links to shared timeout resolution guidance.
docs/​develop/​rust/​activities/​timeouts.mdx Links to shared timeout resolution guidance.
docs/​develop/​ruby/​activities/​timeouts.mdx Links to shared timeout resolution guidance.
docs/​develop/​python/​activities/​timeouts.mdx Links to shared timeout resolution guidance.
docs/​develop/​php/​activities/​timeouts.mdx Adds shared guidance and fixes the Schedule-To-Close link.
docs/​develop/​java/​activities/​timeouts.mdx Links to shared timeout resolution guidance.
docs/​develop/​go/​activities/​timeouts.mdx Links to shared timeout resolution guidance.
docs/​develop/​dotnet/​activities/​timeouts.mdx Links to shared timeout resolution guidance.

Review effort: Balanced

Comment on lines +37 to +38
`temporal activity update-options` builds the mask from the flags you actually pass, so a flag you omit can't clear
anything. A client that builds the mask itself can.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the Activity CLI reference to distinguish the initial scheduling fallback (Schedule-To-Close Timeout, or otherwise Workflow Run Timeout) from update-options, where an omitted flag leaves the stored value unchanged. Commit: 2ea704a9a. The CLI source repository is not part of this checkout, so its help source could not be updated here.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The earlier fix edited docs/cli/command-reference/activity.mdx directly, but that file is generated from temporalio/cli and gets overwritten on each CLI release. I've reverted that edit here and moved the fix to the CLI source in temporalio/cli#1276; the reference will pick it up on the next release.

jsundai and others added 2 commits November 17, 2026 10:48
Clarify timeout settings for activities and workflows.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Clarify timeout behavior in activity updates and scheduling.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
- Replace the infinite Schedule-To-Close and Schedule-To-Start defaults
  on the Go and Java ActivityOptions references with the derived values.
- Note on Pause, Unpause, and Reset that raising Schedule-To-Close
  doesn't raise Start-To-Close, and link to the update rules.
- List Priority and Start Delay among the options Update Options can
  change.
- Drop a repeated "therefore" on the Update Options page.
- Note that temporal activity describe only reports Standalone
  Activities; Workflow Activities show resolved values on the
  ActivityTaskScheduled event.
- State that a Workflow with no Run Timeout leaves Schedule-To-Close and
  Schedule-To-Start unbounded, and that an Execution Timeout alone also
  sets the Run Timeout cap.
- Explain that the CLI can clear a timeout with 0s and that the Service
  derives it again.
- Make the SDK-page sentence cover every timeout the Service fills in.
- Revert the hand edit to the generated CLI reference; the help text fix
  belongs in temporalio/cli.
- **[Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout):** is the maximum amount of time that is allowed from when an [Activity Task](/tasks#activity-task) is scheduled to when a [Worker](/workers#worker) starts that Activity Task. This timeout is non-retryable by design.

An Activity Execution must have either the Start-To-Close or the Schedule-To-Close Timeout set.
The Temporal Service fills in whichever timeouts you leave unset and caps the rest against each other, so the values it stores can differ from the ones you passed. See [How the Temporal Service resolves Activity timeouts](/encyclopedia/detecting-activity-failures#timeout-resolution).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if I like the term fills in. Might update that.

This branch was successfully deployed

1 active deployment
Preview — b63f402f Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify Activity timeout defaults/normalization & explain the UpdateOptions merge-clear-normalize behavior

4 participants