From 21820a7c84f630592b6b66cde50f1e2493bcb8a8 Mon Sep 17 00:00:00 2001 From: John Mueller Date: Tue, 4 Jun 2024 15:18:47 +0200 Subject: [PATCH] Include note about Daylight Savings Time duplication/skipping (#3771) 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 :-)). --- components/time/index.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/components/time/index.rst b/components/time/index.rst index fb62ac596..0332ccc84 100644 --- a/components/time/index.rst +++ b/components/time/index.rst @@ -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 `__ 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