Discussion: Daylight saving time transition clarifications

[odinserj]

Hi @Hexagon! I'm Sergey, the maintainer of Cronos. First of all, I think this is a great attempt to bring structure into the Cron format, as there are a lot of completely different implementations nowadays, and I remember how difficult it was to dig into implementation details, and even sometimes refer to Vixie Cron's source code to get required ideas around this format. I'm not sure I will be able to dedicate enough time working on the specification, but let's at least start with something and see how it goes.

First thing I'd like to clarify is about daylight saving time transitions – this was the reason Cronos was made several years ago. I see it's included in version 1.4 of the specification, but I think one important detail should be added here to make things more intuitive. For example, Cronos defines different behaviors for interval-based expressions, and non-interval based ones to decide whether to skip intervals on DST end or even shift them on DST start.

For example, I expect that the */30 * * * * expression will "running" every 30 minutes, no matter what, and that during DST end, such occurrences should not be skipped. And on the other hand, I'd like to see the 30 02 * * * expression, that has "daily at 02:30 AM" meaning to be executed even during DST start periods that shift time from 02:00 AM to 03:00 AM, to ensure this expression occurs every day – it's so easy to forget about DST and create cron jobs for "bad" time.

But unfortunately, "interval"- and "time-point"-based decisions are full of compromises.

So I have two basic questions to you:

• What is the expected way of discussing/suggesting the changes?
• Have you seen other packages that implement DST rules with cron?

And more complicated ones 😅:

• Should we capitalize "cron"?
• And what is the full definition of it, "cron", "cron expression", "cron pattern"?
• How to name the point of time that satisfies the given cron expression, "occurrence"?

[Hexagon]

Hi Sergey, and welcome!

Regarding your first question about the expected way of discussing/suggesting changes, I've just updated the Contribution section of the README with with suggested guidelines. In short:

• Issues regarding the specification and organization are handled as issues on this repository.
• Finalization of the next iteration is handled as a pull request creating a full specification from its draft.
• Discussions on future iterations, new feature requests, or proposed problems/improvements are handled as separate issues.
• Changes to the README should always be submitted as a pull request.
• When proposing changes to future iterations, it's highly encouraged to open a pull request.

Let's keep this issue for discussions about DST. I will create sub-issues each of the other bullets for discussion 👍

I'll also assign this issue to the 1.4 milestone, and the others to the 1.0

Thanks for joining in!

[Hexagon]

DST is indeed interesting, and your solution in Cronos (separate behavior for interval vs non-interval) is really nice, and aligns with general expectations.

I had a look quick look at how croner (js/ts) handles it:

---

With an interval expression, (*/30 * * * *):

The repeated runs (duplicates) of 01:00 and 01:30 are skipped on autumn; otherwise it's running every 30th minute.

• Spring: OK (in terms of general expectations)
• Autum: Not OK

With a non-interval expression, (0 2 * * *):

The run on the "invalid time" is delayed to 03:00 in spring, and runs as usual on autum (if set to 1, it runs once on the first occurrence of 01:00).

• Spring: OK (in terms of general expectations, it runs the minute after 01:59)
• Autumn: OK

---

Next step is to double-check how these conditions are handled by vixie cron and cronie (it should align with the OCPS 1.4 draft):

4.3.1. Daylight Saving Time (DST) Transitions

For any scheduler implementation, whether it enumerates future run times or polls the current time, handling DST transitions consistently is critical. To align with the time-tested behavior of Vixie cron, the following handling is RECOMMENDED:

• DST Gap (Spring Forward): When a scheduled time falls into a DST gap (an hour that does not exist), the job SHOULD be skipped. It should not run earlier or be delayed until after the transition.
• DST Overlap (Fall Back): When a scheduled time occurs twice due to a DST overlap, the job SHOULD run only once, at the first occurrence.

---

... then figure out if and how we can change the recommendation.

[Hexagon]

On a closer look, it seems like vixie-cron handles this scenario closer to Cronos than the current (previous draft of the) specification.

Looking at the loop at https://github.com/vixie/cron/blob/9cc8ab1087bb9ab861dd5595c41200683c9f6712/cron.c#L135

	/*
	 * Too many clocks, not enough time (Al. Einstein)
	 * These clocks are in minutes since the epoch, adjusted for timezone.
	 * virtualTime: is the time it *would* be if we woke up
	 * promptly and nobody ever changed the clock. It is
	 * monotonically increasing... unless a timejump happens.
	 * At the top of the loop, all jobs for 'virtualTime' have run.
	 * timeRunning: is the time we last awakened.
	 * clockTime: is the time when set_time was last called.
	 */
	while (TRUE) {
		/* ... wait for the time (in minutes) to change ... */
		/*
		 * Calculate how the current time differs from our virtual
		 * clock.  Classify the change into one of 4 cases.
		 */
		/* shortcut for the most common case */
		if (timeDiff == 1) {
			virtualTime = timeRunning;
			find_jobs(virtualTime, &database, TRUE, TRUE);
		} else {
			if (timeDiff > (3*MINUTE_COUNT) ||
			    timeDiff < -(3*MINUTE_COUNT))
				wakeupKind = large;
			else if (timeDiff > 5)
				wakeupKind = medium;
			else if (timeDiff > 0)
				wakeupKind = small;
			else
				wakeupKind = negative;

			switch (wakeupKind) {
			case small:
				/*
				 * case 1: timeDiff is a small positive number
				 * (wokeup late) run jobs for each virtual
				 * minute until caught up.
				 */
			case medium:
				/*
				 * case 2: timeDiff is a medium-sized positive
				 * number, for example because we went to DST
				 * run wildcard jobs once, then run any
				 * fixed-time jobs that would otherwise be
				 * skipped if we use up our minute (possible,
				 * if there are a lot of jobs to run) go
				 * around the loop again so that wildcard jobs
				 * have a chance to run, and we do our
				 * housekeeping.
				 */
				/* run fixed-time jobs for each minute missed */
			case negative:
				/*
				 * case 3: timeDiff is a small or medium-sized
				 * negative num, eg. because of DST ending.
				 * Just run the wildcard jobs. The fixed-time
				 * jobs probably have already run, and should
				 * not be repeated.  Virtual time does not
				 * change until we are caught up.
				 */
			default:
				/*
				 * other: time has changed a *lot*,
				 * jump virtual time, and run everything
				 */
			}
		}

How about this for 4.3.1:

---

4.3.1. Daylight Saving Time (DST) Transitions

Consistent handling of Daylight Saving Time (DST) transitions is critical for any cron scheduler. To ensure interoperability and align with the time-tested behavior of Vixie cron, the following handling is RECOMMENDED:

Job patterns are categorized based on their Seconds, Minute, and Hour field specifications:

• Fixed-Time Job: A cron pattern where the Seconds, Minute, and Hour fields all specify a single, fixed numerical value, or a list/range of specific numerical values. Wildcards (*) or step values (*/N) are NOT used in these time-unit fields.

  • (Examples: 0 30 2 * * * (no seconds), 0 0 30 2 * * * (with seconds))

• Interval/Wildcard Job: A cron pattern where at least one of the Seconds, Minute, or Hour fields uses a wildcard (*) or a step value (*/N).

  • (Examples: * * * * * * (seconds), 0 */5 * * * * (minutes), 0 0 */2 * * * (hours))

4.3.1.1 DST Gap (Spring Forward)

When the clock advances and a scheduled time interval is skipped (e.g., 2:00 AM jumps to 3:00 AM):

• Fixed-Time Jobs: If a fixed-time job's scheduled time falls within a DST gap, the job SHOULD be executed at the first valid second/minute immediately following the gap on the same calendar day. This ensures the job runs with minimal delay on its intended day.

• Interval/Wildcard Jobs: If an interval/wildcard job's scheduled time falls within a DST gap, occurrences within the gap SHOULD be skipped. Subsequent executions SHOULD resume at the next regularly scheduled interval relative to the new wall clock time.

4.3.1.2 DST Overlap (Fall Back)

When the clock rolls back and a minute/hour interval occurs twice (e.g., 2:00 AM falls back to 1:00 AM):

• For Fixed-Time Jobs: If a scheduled time (including seconds, minutes, and hours) occurs twice due to a DST overlap, the job SHOULD execute only once, at its first occurrence in wall clock time. Subsequent occurrences of the same absolute time within the repeated hour MUST NOT trigger a re-run.
• For Interval/Wildcard Jobs: If a scheduled time (including seconds, minutes, and hours) occurs twice due to a DST overlap, the job SHOULD execute for each occurrence that matches its pattern in wall clock time. This will result in multiple executions for the same logical second/minute within the duplicated hour.

---

I think this aligns well with both vixie-cron, cronie and cronos. A couple of questions arise:

• Do you agree on the above @vixie and @odinserj?
• Should we make this behavior a recommendation directly in 1.0, and a requirement through 1.4?