Lee-W commented on code in PR #51603: URL: https://github.com/apache/airflow/pull/51603#discussion_r2139278721
########## airflow-core/docs/installation/upgrading_to_airflow3.rst: ########## @@ -46,31 +46,40 @@ Step 2: Clean and back up your existing Airflow Instance ensure you deploy your changes to your old instance prior to upgrade, and wait until your dags have all been reprocessed (and all errors gone) before you proceed with upgrade. -Step 3: DAG Authors - Check your Airflow DAGs for compatibility +Step 3: Dag Authors - Check your Airflow dags for compatibility ---------------------------------------------------------------- -To minimize friction for users upgrading from prior versions of Airflow, we have created a dag upgrade check utility using `Ruff <https://docs.astral.sh/ruff/>`_. +To minimize friction for users upgrading from prior versions of Airflow, we have created a dag upgrade check utility using `Ruff <https://docs.astral.sh/ruff/>`_ combined with `AIR <https://docs.astral.sh/ruff/rules/#airflow-air>`_ rules. The rules AIR301 and AIR302 indicate breaking changes in Airflow 3, while AIR311 and AIR312 highlight changes that are not currently breaking but are strongly recommended for updates. -The latest available ``ruff`` version will have the most up-to-date rules, but be sure to use at least version ``0.11.6``. The below example demonstrates how to check -for dag incompatibilities that will need to be fixed before they will work as expected on Airflow 3. +The latest available ``ruff`` version will have the most up-to-date rules, but be sure to use at least version ``0.11.13``. The below example demonstrates how to check for dag incompatibilities that will need to be fixed before they will work as expected on Airflow 3. .. code-block:: bash - ruff check dag/ --select AIR301 --preview + ruff check dags/ --select AIR301 --preview To preview the recommended fixes, run the following command: .. code-block:: bash - ruff check dag/ --select AIR301 --show-fixes --preview + ruff check dags/ --select AIR301 --show-fixes --preview Some changes can be automatically fixed. To do so, run the following command: .. code-block:: bash - ruff check dag/ --select AIR301 --fix --preview + ruff check dags/ --select AIR301 --fix --preview +Some of the fixes are marked as unsafe. To trigger these fixes, run the following command: + +.. code-block:: bash + + ruff check dags/ --select AIR301 --fix --unsafe-fixes --preview + +Unsafe fixes usually do not break dag code. They're marked as safe as they may change some runtime behavior. For more information, see `Fix Safety <https://docs.astral.sh/ruff/linter/#fix-safety>`_. + +In AIR rules, unsafe fixes involve changing import paths while keeping the name of the imported member the same. For instance, changing the import from ``from airflow.sensors.base_sensor_operator import BaseSensorOperator`` to ``from airflow.sdk.bases.sensor import BaseSensorOperator`` requires ruff to remove the original import before adding the new one. In contrast, safe fixes include changes to both the member name and the import path, such as changing ``from airflow.datasets import Dataset`` to `from airflow.sdk import Asset``. These adjustments do not require ruff to remove the old import. To remove unused legacy imports, it is necessary to enable the `unused-import` rule (F401) <https://docs.astral.sh/ruff/rules/unused-import/#unused-import-f401>. Review Comment: put it to `.. note::` sounds like a good idea. Will update it According to the Ruff doc, I believe any runtime change should be marked as unsafe. `airflow.sensors.base_sensor_operator.BaseSensorOperator` is not entirely the same as `airflow.sdk.bases.sensor.BaseSensorOperator`, especially if users are checking the import path in some circumstances. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
