Skip to content

Document DST handling behavior comprehensively #70

@CybotTM

Description

@CybotTM

Summary

DST (Daylight Saving Time) handling is partially implemented and documented, but users need comprehensive guidance on edge cases.

Current State

Documentation Gaps

1. Spring Forward (Clock Jumps Ahead)

  • Jobs scheduled in skipped hour: ✅ Run immediately (documented in code)
  • User documentation: ❌ Not in README or docs/

2. Fall Back (Clock Repeats Hour)

  • Jobs scheduled in repeated hour: ❓ Behavior unclear
  • Does job run once or twice?
  • Which occurrence is used?

3. Timezone-Specific Behavior

  • Different regions have different DST rules
  • Some regions don't observe DST
  • Historical DST changes

4. Schedule Location vs System Location

  • WithLocation() affects parsing
  • SpecSchedule.Location affects execution
  • Interaction is complex

Required Documentation

README Section

## Daylight Saving Time Handling

### Spring Forward (Clocks Jump Ahead)
When DST causes clocks to spring forward, any jobs scheduled to run 
during the skipped hour will run immediately when the clock jumps.

Example: If DST skips 2:00 AM to 3:00 AM, a job scheduled for 2:30 AM
will run at 3:00 AM.

### Fall Back (Clocks Repeat Hour)
[Document actual behavior]

### Timezone Configuration
[Document WithLocation and SpecSchedule.Location interaction]

docs/DST_HANDLING.md

Comprehensive guide with:

  • All DST scenarios
  • Examples for different timezones
  • Testing recommendations
  • Known limitations

Acceptance Criteria

  • Document spring-forward behavior in README
  • Document fall-back behavior (clarify or implement)
  • Create docs/DST_HANDLING.md
  • Add examples for common DST scenarios
  • Test coverage for fall-back scenario
  • Document timezone configuration options

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationhigh-priorityHigh priority issues

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions