This is an automated email from the ASF dual-hosted git repository.
ashb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 76f2e8ee7f4 Document timetable switch effects when
create_cron_data_intervals flips (#66441)
76f2e8ee7f4 is described below
commit 76f2e8ee7f4c4519215ca6e292277f689aad269a
Author: Jed Cunningham <[email protected]>
AuthorDate: Wed May 6 00:53:35 2026 -0600
Document timetable switch effects when create_cron_data_intervals flips
(#66441)
---
RELEASE_NOTES.rst | 4 ++--
.../docs/authoring-and-scheduling/timetable.rst | 23 ++++++++++++++++++++++
.../docs/installation/upgrading_to_airflow3.rst | 16 ++++++++++++++-
reproducible_build.yaml | 4 ++--
4 files changed, 42 insertions(+), 5 deletions(-)
diff --git a/RELEASE_NOTES.rst b/RELEASE_NOTES.rst
index 54e8e396764..d18b9e7497b 100644
--- a/RELEASE_NOTES.rst
+++ b/RELEASE_NOTES.rst
@@ -2570,7 +2570,7 @@ Several default configuration values have been updated in
Airflow 3.0 to better
simplify onboarding:
- ``catchup_by_default`` is now set to ``False`` by default. DAGs will not
automatically backfill unless explicitly configured to do so.
-- ``create_cron_data_intervals`` is now set to ``False`` by default. As a
result, cron expressions will be interpreted using the ``CronTriggerTimetable``
instead of the legacy ``CronDataIntervalTimetable``.
+- ``create_cron_data_intervals`` is now set to ``False`` by default. As a
result, cron expressions will be interpreted using the ``CronTriggerTimetable``
instead of the legacy ``CronDataIntervalTimetable``. This only affects DAGs
that pass a bare cron string to ``schedule=``; DAGs that pass an explicit
timetable instance are unaffected. If you rely on the data interval semantics
(``data_interval_start`` / ``data_interval_end``, or templated values like
``ds`` / ``ts`` derived from ``logi [...]
- ``SimpleAuthManager`` is now the default ``auth_manager``. To continue using
Flask AppBuilder-based authentication, install the
``apache-airflow-providers-fab`` provider and explicitly set ``auth_manager =
airflow.providers.fab.auth_manager.FabAuthManager``.
These changes represent the most significant evolution of the Airflow platform
since the release of 2.0 — setting the
@@ -2822,7 +2822,7 @@ Refactored Config Defaults
Several configuration defaults have changed in Airflow 3.0 to better reflect
modern usage patterns:
- The default value of ``catchup_by_default`` is now ``False``. DAGs will not
backfill missed intervals unless explicitly configured to do so.
-- The default value of ``create_cron_data_intervals`` is now ``False``. Cron
expressions are now interpreted using the ``CronTriggerTimetable`` instead of
the legacy ``CronDataIntervalTimetable``. This change simplifies interval logic
and aligns with the future direction of Airflow's scheduling system.
+- The default value of ``create_cron_data_intervals`` is now ``False``. Cron
expressions are now interpreted using the ``CronTriggerTimetable`` instead of
the legacy ``CronDataIntervalTimetable``. This change simplifies interval logic
and aligns with the future direction of Airflow's scheduling system. Set this
flag explicitly **before** upgrading from Airflow 2 if you rely on data
interval semantics; flipping it later (after Airflow 3 DAG runs exist) will
skip one scheduled run per affe [...]
Refactored Internal Utilities
"""""""""""""""""""""""""""""
diff --git a/airflow-core/docs/authoring-and-scheduling/timetable.rst
b/airflow-core/docs/authoring-and-scheduling/timetable.rst
index 28957370a47..b19cc802113 100644
--- a/airflow-core/docs/authoring-and-scheduling/timetable.rst
+++ b/airflow-core/docs/authoring-and-scheduling/timetable.rst
@@ -357,6 +357,29 @@ In these examples, you see how a trigger timetable creates
Dag runs more intuiti
people expect a workflow to behave, while a data interval timetable is
designed heavily around the data
interval it processes, and does not reflect a workflow's own properties.
+Switching between trigger and data interval timetables on an existing Dag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The two kinds of timetable anchor ``logical_date`` differently: a trigger
+timetable uses the trigger time, a data interval timetable uses
+``data_interval_start``. Switching a Dag from a trigger timetable to a data
+interval timetable when it already has existing dagruns will skip one
+scheduled run, because the next run is advanced one period to avoid colliding
+with the previous run's ``logical_date``. The reverse direction (data
+interval -> trigger) does not skip a run.
+
+This transition can happen without editing a Dag, in two ways:
+
+- Flipping ``[scheduler] create_cron_data_intervals`` changes how every Dag
+ with a bare cron string in ``schedule=`` resolves its timetable.
+- Crossing a version boundary where the default differs. Airflow 3 defaults
+ to ``False``; Airflow 2.x defaults to ``True``.
+
+To keep ``logical_date`` semantics stable across either change, decide which
+timetable you want and pin it before the change: set the flag explicitly to
+the same value on both sides, or convert affected Dags to use an explicit
+timetable instance in ``schedule=`` so the flag no longer applies.
+
.. _Differences between the cron and delta data interval timetables:
diff --git a/airflow-core/docs/installation/upgrading_to_airflow3.rst
b/airflow-core/docs/installation/upgrading_to_airflow3.rst
index 41151e98df7..4020aee4634 100644
--- a/airflow-core/docs/installation/upgrading_to_airflow3.rst
+++ b/airflow-core/docs/installation/upgrading_to_airflow3.rst
@@ -373,7 +373,21 @@ These include:
- ``next_ds``
- ``execution_date``
- The ``catchup_by_default`` Dag parameter is now ``False`` by default.
-- The ``create_cron_data_intervals`` configuration is now ``False`` by
default. This means that the ``CronTriggerTimetable`` will be used by default
instead of the ``CronDataIntervalTimetable``
+- The ``create_cron_data_intervals`` configuration is now ``False`` by
default. This means that the ``CronTriggerTimetable`` will be used by default
instead of the ``CronDataIntervalTimetable``.
+
+ This only affects Dags that pass a **bare cron string** to ``schedule=``
(e.g.
+ ``schedule="0 0 * * *"``); Dags that pass an explicit timetable instance are
+ unaffected. Decide whether you rely on ``data_interval_start`` /
+ ``data_interval_end`` (and on the related templated values like ``ds`` /
+ ``ts`` in your tasks, which are derived from ``logical_date`` and shift
+ between the two timetables). If you do, set
+ ``create_cron_data_intervals=True`` explicitly to keep
``CronDataIntervalTimetable``.
+ If you don't, the new ``False`` default is fine.
+
+ Set this **before** the upgrade. If you instead change the flag after some
+ Airflow 3 dagruns already exist (going
+ ``CronTriggerTimetable`` -> ``CronDataIntervalTimetable``), one scheduled run
+ is skipped to avoid colliding with the previous run's ``logical_date``.
- **Simple Auth** is now default ``auth_manager``. To continue using FAB as
the Auth Manager, please install the FAB provider and set ``auth_manager`` to
``FabAuthManager``:
.. code-block:: ini
diff --git a/reproducible_build.yaml b/reproducible_build.yaml
index 2ae3c849db9..ae760a9b86f 100644
--- a/reproducible_build.yaml
+++ b/reproducible_build.yaml
@@ -1,2 +1,2 @@
-release-notes-hash: e8a64f3862bb824afdef79a5b43e10ca
-source-date-epoch: 1776850682
+release-notes-hash: d5d083e22e941ed99b0ebf346d6dced4
+source-date-epoch: 1777936674
