(airflow) branch main updated: Improve Airflow 3 import deprecation documentation (#55722)

[am...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

amoghdesai 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 6b93f9fbbcc Improve Airflow 3 import deprecation documentation (#55722)
6b93f9fbbcc is described below

commit 6b93f9fbbcc6f994abac0e6d6f52759a8c5150d8
Author: Amogh Desai <am...@gmail.com>
AuthorDate: Tue Sep 16 21:53:17 2025 +0530

    Improve Airflow 3 import deprecation documentation (#55722)
---
 .../docs/installation/upgrading_to_airflow3.rst    | 62 ++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/airflow-core/docs/installation/upgrading_to_airflow3.rst b/airflow-core/docs/installation/upgrading_to_airflow3.rst
index 115c3366535..ecd7090fd07 100644
--- a/airflow-core/docs/installation/upgrading_to_airflow3.rst
+++ b/airflow-core/docs/installation/upgrading_to_airflow3.rst
@@ -122,6 +122,68 @@ To trigger these fixes, run the following command:
 
 You can also configure these flags through configuration files. See `Configuring Ruff <https://docs.astral.sh/ruff/configuration/>`_ for details.
 
+Key Import Updates
+^^^^^^^^^^^^^^^^^^
+
+While ruff can automatically fix many import issues, here are the key import changes you'll need to make to ensure your DAGs and other
+code import Airflow components correctly in Airflow 3. The older paths are deprecated and will be removed in a future Airflow version.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 50, 50
+
+   * - **Old Import Path (Deprecated)**
+     - **New Import Path (airflow.sdk)**
+   * - ``airflow.decorators.dag``
+     - ``airflow.sdk.dag``
+   * - ``airflow.decorators.task``
+     - ``airflow.sdk.task``
+   * - ``airflow.decorators.task_group``
+     - ``airflow.sdk.task_group``
+   * - ``airflow.decorators.setup``
+     - ``airflow.sdk.setup``
+   * - ``airflow.decorators.teardown``
+     - ``airflow.sdk.teardown``
+   * - ``airflow.models.dag.DAG``
+     - ``airflow.sdk.DAG``
+   * - ``airflow.models.baseoperator.BaseOperator``
+     - ``airflow.sdk.BaseOperator``
+   * - ``airflow.models.param.Param``
+     - ``airflow.sdk.Param``
+   * - ``airflow.models.param.ParamsDict``
+     - ``airflow.sdk.ParamsDict``
+   * - ``airflow.models.baseoperatorlink.BaseOperatorLink``
+     - ``airflow.sdk.BaseOperatorLink``
+   * - ``airflow.sensors.base.BaseSensorOperator``
+     - ``airflow.sdk.BaseSensorOperator``
+   * - ``airflow.hooks.base.BaseHook``
+     - ``airflow.sdk.BaseHook``
+   * - ``airflow.notifications.basenotifier.BaseNotifier``
+     - ``airflow.sdk.BaseNotifier``
+   * - ``airflow.utils.task_group.TaskGroup``
+     - ``airflow.sdk.TaskGroup``
+   * - ``airflow.datasets.Dataset``
+     - ``airflow.sdk.Asset``
+   * - ``airflow.datasets.DatasetAlias``
+     - ``airflow.sdk.AssetAlias``
+   * - ``airflow.datasets.DatasetAll``
+     - ``airflow.sdk.AssetAll``
+   * - ``airflow.datasets.DatasetAny``
+     - ``airflow.sdk.AssetAny``
+   * - ``airflow.models.connection.Connection``
+     - ``airflow.sdk.Connection``
+   * - ``airflow.models.context.Context``
+     - ``airflow.sdk.Context``
+   * - ``airflow.models.variable.Variable``
+     - ``airflow.sdk.Variable``
+   * - ``airflow.io.*``
+     - ``airflow.sdk.io.*``
+
+**Migration Timeline**
+
+- **Airflow 3.1**: Legacy imports show deprecation warnings but continue to work
+- **Future Airflow version**: Legacy imports will be **removed**
+
 Step 4: Install the Standard Provider
 --------------------------------------