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 b94e213a569 docs(contributing-docs): avoid raise AirflowException
directly (#55420)
b94e213a569 is described below
commit b94e213a5694ec35bf99083daa5105d593eddfd8
Author: Wei Lee <[email protected]>
AuthorDate: Mon Sep 15 15:10:41 2025 +0800
docs(contributing-docs): avoid raise AirflowException directly (#55420)
---
contributing-docs/05_pull_requests.rst | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)
diff --git a/contributing-docs/05_pull_requests.rst
b/contributing-docs/05_pull_requests.rst
index 9d50aca692d..17857e2696f 100644
--- a/contributing-docs/05_pull_requests.rst
+++ b/contributing-docs/05_pull_requests.rst
@@ -275,6 +275,32 @@ The reason for doing it is that we are working on a
cleaning up our code to have
that will make sure all the cases where logic (such as validation and complex
conversion)
is not done in the constructor are detected in PRs.
+Don't raise AirflowException directly
+..............................................
+
+Our community has decided to stop adding new ``raise AirflowException`` and to
adopt the following practices when an exception is necessary. For details check
the relevant `mailing list thread
<hhttps://lists.apache.org/thread/t8bnhyqy77kq4fk7fj3fmjd5wo9kv6w0>`_.
+
+1. In most cases, we should prioritize using Python’s standard exceptions
(e.g., ``ValueError``, ``TypeError``, ``OSError``)
+ instead of wrapping everything in ``AirflowException``.
+2. Within ``airflow-core``, we should define and utilize more specific
exception classes under ``airflow-core/src/airflow/exceptions.py``.
+3. For provider-specific implementations, exceptions should be defined within
``providers/<provider>/src/airflow/providers/<provider>/exceptions.py``.
+
+The use of points 2 and 3 should only be considered when point 1 is
inappropriate, which should be a rare occurrence.
+
+In other words instead of doing:
+
+.. code-block:: python
+
+ if key not in conf:
+ raise AirflowException(f"Required key {key} is missing")
+
+you should do:
+
+.. code-block:: python
+
+ if key not in conf:
+ raise ValueError(f"Required key {key} is missing")
+
-----------
If you want to learn what are the options for your development environment,
follow to the
