This is an automated email from the ASF dual-hosted git repository.
weilee 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 a6f9357dbf3 docs: How to propose an Airflow best practice and a
corresponding Ruff AIR rules (#63190)
a6f9357dbf3 is described below
commit a6f9357dbf30a30ab40fc4bb07947c4aa1d0efb7
Author: Wei Lee <[email protected]>
AuthorDate: Sun Mar 15 22:42:14 2026 +0800
docs: How to propose an Airflow best practice and a corresponding Ruff AIR
rules (#63190)
---
airflow-core/docs/best-practices.rst | 13 +++++--
.../24_proposing_best_practices_and_air_rules.rst | 42 ++++++++++++++++++++++
2 files changed, 52 insertions(+), 3 deletions(-)
diff --git a/airflow-core/docs/best-practices.rst
b/airflow-core/docs/best-practices.rst
index 5a49ac86cd0..7fd7a7be5ed 100644
--- a/airflow-core/docs/best-practices.rst
+++ b/airflow-core/docs/best-practices.rst
@@ -299,9 +299,16 @@ This means that the ``get_array`` is not executed as
top-level code, but ``get_t
Code Quality and Linting
------------------------
-Maintaining high code quality is essential for the reliability and
maintainability of your Airflow workflows. Utilizing linting tools can help
identify potential issues and enforce coding standards. One such tool is
``ruff``, a fast Python linter that now includes specific rules for Airflow.
-
-ruff assists in detecting deprecated features and patterns that may affect
your migration to Airflow 3.0. For instance, it includes rules prefixed with
``AIR`` to flag potential issues. The full list is detailed in `Airflow (AIR)
<https://docs.astral.sh/ruff/rules/#airflow-air>`_.
+Maintaining high code quality is essential for the reliability and
maintainability of your Airflow workflows.
+The following points summarize how this relates to Ruff:
+
+1. This page documents Airflow best practices. Some of those practices are
also supported by Ruff ``AIR`` rules,
+ which help detect and enforce Airflow-specific best practices, including
deprecated patterns and migration issues.
+ The full list is available in
+ `Airflow (AIR) <https://docs.astral.sh/ruff/rules/#airflow-air>`_.
+2. If you want to suggest a new Airflow best practice and add a matching Ruff
``AIR`` rule, follow the contributor
+ process described in
+ `Proposing Airflow Best Practices and Ruff AIR Rules
<https://github.com/apache/airflow/blob/main/contributing-docs/24_proposing_best_practices_and_air_rules.rst>`_.
Installing and Using ruff
-------------------------
diff --git a/contributing-docs/24_proposing_best_practices_and_air_rules.rst
b/contributing-docs/24_proposing_best_practices_and_air_rules.rst
new file mode 100644
index 00000000000..45f5fd551c9
--- /dev/null
+++ b/contributing-docs/24_proposing_best_practices_and_air_rules.rst
@@ -0,0 +1,42 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Proposing Airflow Best Practices and Ruff AIR Rules
+===================================================
+
+This document explains how to propose a new Airflow best practice and, when
appropriate, a matching Ruff
+``AIR`` rule.
+
+Not every best practice needs a linter rule, but for practices that can be
checked automatically, ``AIR`` rules
+help contributors and users detect issues early and keep code consistent.
+
+Proposal process
+----------------
+
+1. Begin the voting process or initiate a Lazy Consensus regarding migration,
deprecation,
+ or any other issue where there is strong community agreement. If someone
opposes the decision,
+ we can revisit the discussion and hold another vote.
+2. Once the vote or Lazy Consensus is approved, create a pull request and
update the Airflow best practices documentation.
+ At this point, the development of Ruff rules can proceed concurrently.
+3. After the pull request for Ruff is merged, ensure that the relevant
documentation is updated to incorporate
+ the new Ruff rules accordingly.
+
+See also
+--------
+
+* `How to communicate <02_how_to_communicate.rst>`__
+* `ASF Voting Process <https://www.apache.org/foundation/voting.html>`__
