dst-transition-reference

Overview

DST transitions cause a large share of production time-bugs: spring-forward creates non-existent local times, fall-back creates duplicate local times. The IANA Time Zone Database (iana.org/time-zones) is the canonical source of historical and current DST rules.

How to use this reference

1. Identify the transition the code crosses - spring-forward (skipped hour) or fall-back (repeated hour) - from the DST mechanics section below.
2. Match the bug class the code is exposed to (cron, billing, duration arithmetic, recurring meeting, storage) and apply its mitigation.
3. Turn it into an assertion using the testable-behaviours table - construct the transition timestamp and assert the library's documented result (see the worked example).
4. Pick zones + fixture timestamps from references/jurisdictions-and-fixtures.md, then refresh them against IANA before each release.

When to use

• Designing time-handling code that crosses DST boundaries.
• Auditing existing code for DST-safety.
• Writing test cases that exercise DST behaviour.
• Investigating "scheduled job ran twice / didn't run" reports.

DST mechanics

Spring-forward (skipped hour)

Per en.wikipedia.org/wiki/Daylight_saving_time, in US Eastern: on the 2nd Sunday of March, at 02:00 local time the clock jumps to 03:00. The 02:00-02:59 hour does not exist in local time.

Tests against 2026-03-08 02:30 America/New_York produce ambiguous or invalid results depending on library:

Fall-back (repeated hour)

In US Eastern: 1st Sunday of November at 02:00 local time, the clock falls back to 01:00. The 01:00-01:59 hour occurs twice - once as EDT (UTC-4), once as EST (UTC-5).

2026-11-01 01:30 America/New_York is ambiguous. Libraries either:

• Pick one (typically the first occurrence in pytz/zoneinfo)
• Raise an error
• Take an is_dst / fold flag (Python 3.6+ has fold=0|1)

Worked example - a spring-forward assertion

Goal: prove the code under test handles a non-existent local time deterministically.

1. Pick the transition: America/New_York spring-forward on 2026-03-08 - 02:00 local jumps to 03:00, so 02:00-02:59 does not exist.
2. Construct 2026-03-08 02:30 America/New_York in the code path.
3. Assert against the library's documented behaviour (from the table above):
   • Python zoneinfo normalises to 03:30 EDT - assert the normalised value, never 02:30.
   • Python pytz raises NonExistentTimeError - assert the raise.
   • Java ZonedDateTime applies its resolver - assert per the chosen STRICT / SMART_FORWARD rule.
4. Repeat for fall-back: 2026-11-01 01:30 America/New_York occurs twice; assert the fold / is_dst selection picks the intended offset.

Per-jurisdiction differences

Per-region DST rules (US, EU, Australia, and the growing list of regions that abolished DST) and refreshable 2026 fixture timestamps live in references/jurisdictions-and-fixtures.md. Per IANA, rules change frequently - test against current zoneinfo, not assumptions.

Common bug classes

Cron jobs

A "daily at 02:30" cron in America/New_York:

• Spring-forward day: doesn't fire (02:30 doesn't exist).
• Fall-back day: fires twice (02:30 EDT, then 02:30 EST).

Mitigation:

• Use UTC cron expressions when possible.
• For local-time business hours, accept the irregularity or schedule outside transition hours (04:00 is safe everywhere).
• Per cron-job-test-author (in the qa-async-jobs plugin): always test DST + leap-day edge cases.

Billing periods

"Bill on the 1st of each month at 00:00 local time":

• Fine in jurisdictions without DST.
• Risk in DST-observing: 00:00 local on Nov 1 (US) might overlap with the fall-back hour if billing involves more than one event.

Mitigation: bill at UTC, or at a local hour known to be safe (e.g., 06:00).

Duration arithmetic

tomorrow_same_time = today_same_time + Duration("24 hours"):

• Spring-forward: result is 23 hours later in local time.
• Fall-back: result is 25 hours later in local time.

Mitigation: distinguish "24 hours from now" (Duration) from "this time tomorrow" (calendar addition).

Recurring meeting

"Every Monday at 09:00 local time":

• Crosses DST boundary → still 09:00 local, but 2 minutes before or after the UTC equivalent of the previous week.
• Calendar systems handle this; custom scheduling code often doesn't.

Storage

Storing wall-clock-local strings ("2026-03-08 02:30") is unsafe across DST. Always store UTC + zone identifier.

Testable behaviours

Per timezone-test-matrix-builder, the test matrix combines (zone, transition-type, library-version).

Anti-patterns

Limitations

• IANA zoneinfo changes throughout the year. Sept 2026 may add or remove DST observance for some jurisdictions; test data goes stale.
• OS / runtime zoneinfo versions differ. Java's tzdata ships with the JDK; system tzdata is separate; Python's zoneinfo reads system tzdata. Mismatches cause subtle bugs.
• Polar regions, antimeridian, and historic timezones. Special cases not covered here.
• Doesn't address leap seconds. See leap-second-reference.

References

• IANA Time Zone Database: www.iana.org/time-zones.
• Wikipedia DST: en.wikipedia.org/wiki/Daylight_saving_time.
• Python zoneinfo: docs.python.org/3/library/zoneinfo.html.
• Deep reference (with its own citations): per-jurisdiction rules + fixtures in references/jurisdictions-and-fixtures.md.
• Companion catalogs: leap-second-reference, iso-8601-vs-rfc-3339-reference.
• Cross-plugin: cron-job-test-author (qa-async-jobs).
• Consumed by: libfaketime-c, sinon-fake-timers-js, jest-fake-timers, freezegun-python, timecop-ruby, mockclock-jvm, timezone-test-matrix-builder.