Include note about Daylight Savings Time duplication/skipping

It's probably clear to most people that setting up a trigger for the 31st of every month will fail in February, but apparently triggers between 1am and 3am are also fragile once a year. For non-disruptive or regular triggers, this might not be an issue -- if you want to turn off a device at 2am using on_time, you should know that it will fail once a week. Similarly, if you want to do a daily trigger at 1am, you should know that it will trigger twice a day once a year. 

This does not seem super-obvious until you've run into it, so I propose adding a note to the documentation. It also doesn't feel like something that should be changed in the functionality to match cron's behavior, given that it would change the functionality of existing triggers. 

I'm not invested in the exact wording / location; I suspect pulling it out a bit into a more visible place makes it less likely for people to miss.

(Brought to you by a trigger that turns off an expensive device at 2am, only for it to run a full day instead :-)).
This commit is contained in:
John Mueller 2024-04-19 16:55:41 +02:00 committed by GitHub
parent db5b1de530
commit 2d5e23862f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 9 additions and 0 deletions

View File

@ -181,6 +181,15 @@ In the ``seconds:``, ``minutes:``, ... fields you can use the following operator
then:
- switch.toggle: my_switch
.. note::
``on_time`` does not re-schedule events for times that are skipped or duplicated due to local Daylight
Saving Time or other local time-adjustments like leap seconds. In regions with Daylight Saving Time, this
means that events located between 01:00 - 02:00 may trigger twice, and events scheduled between 02:00 - 03:00 may
be skipped once a year. This differs from `cron <https://man7.org/linux/man-pages/man8/cron.8.html>`__ behavior
despite allowing the use of similar `crontab` syntax. Similarly, triggers on days of the month that do not exist
("every 31st of the month") will be skipped when those dates do not exist.
.. _time-on_time_sync:
``on_time_sync`` Trigger