Skip to content

Define and document how existing Schedules pick up tzdata updates #13197

Open

Description

@XiNiHa

Is your feature request related to a problem? Please describe.

A Schedule using an IANA timezone_name may remain active while timezone rules change—for example, when a region introduces or abolishes DST. It is unclear when existing Schedules pick up updated server tzdata, and whether already-calculated execution times are reconsidered.

This concerns changes to the timezone rules themselves, not ordinary DST transitions already represented in tzdata.

The legacy Cron Job documentation describes “Absolute Time Fixed at Start”, but I could not find an equivalent explanation for the Schedule API. This makes it difficult to ensure that infrequent or far-future actions continue to run at their intended local time.

Describe the solution you'd like

Please define and document how tzdata updates propagate to existing Schedules, including:

  • When cached timezone definitions and compiled schedule specs are refreshed.
  • Whether pending timers and cached future action times are recalculated.
  • Whether service restarts or explicit Schedule updates are required.
  • Whether behavior differs between scheduler implementations.

Ideally, existing calendar-based Schedules using timezone_name without explicit timezone_data would adopt updated rules within a documented, bounded period and reconsider pending execution times. If automatic refresh is unsupported, a supported operation to refresh affected Schedules would be useful.

Describe alternatives you've considered

  • Using UTC: this does not preserve the intended local wall-clock time when timezone rules change.
  • Explicitly supplying timezone_data: this gives control over the rules but requires the application to maintain and update them.
  • Updating or recreating affected Schedules after a tzdata update: this requires identifying all affected Schedules, and the supported procedure and refresh guarantees are unclear.

Additional context

From source inspection, SpecBuilder caches time.LoadLocation results with a 24-hour TTL. However, cache expiry alone does not appear to invalidate existing compiled specs or reschedule pending timers. The workflow-based scheduler compiles its spec at startup and on Schedule updates.

Source inspected:
https://github.com/temporalio/temporal/blob/2c8ae4e89b37d69e50aad460f4264b03447e6054/service/worker/scheduler/spec.go
https://github.com/temporalio/temporal/blob/2c8ae4e89b37d69e50aad460f4264b03447e6054/service/worker/scheduler/workflow.go

Scenario to verify (not yet reproduced):

  1. Create an infrequent calendar Schedule using timezone_name.
  2. Let the scheduler calculate its next action time.
  3. Update server tzdata so that the same local occurrence maps to an earlier UTC time.
  4. Leave the Schedule unchanged and check whether it fires at the newly correct time.

AI assistance disclosure: I used GPT 6 Astra to help investigate the documentation and source code and draft this issue.

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

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      ⌂ 换网址