This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch v3-2-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/v3-2-test by this push:
new 51144dc9955 [v3-2-test] Add AGENTS.md for dev/ and scripts/ci/prek/
(#64434) (#64435)
51144dc9955 is described below
commit 51144dc995544bde36f1699905d5eadd4e16adcb
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Wed Apr 1 13:44:36 2026 +0200
[v3-2-test] Add AGENTS.md for dev/ and scripts/ci/prek/ (#64434) (#64435)
* Add AGENTS.md guidelines for dev/ scripts
New scripts in dev/ should be standalone Python (not bash) with inline
script metadata so they can be run via `uv run`.
* Add AGENTS.md guidelines for dev/ and scripts/ci/prek/
Add coding guidelines for AI agents working in these directories:
- dev/AGENTS.md: new scripts must be standalone Python with inline
script metadata (after the license header), run via `uv run`.
- scripts/ci/prek/AGENTS.md: use common_prek_utils.py helpers,
breeze-dependent hooks go at the end of .pre-commit-config.yaml.
(cherry picked from commit beade8e26f63e37bd74c755fcaebfafec17c74fa)
Co-authored-by: Jarek Potiuk <[email protected]>
---
dev/AGENTS.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
scripts/ci/prek/AGENTS.md | 31 +++++++++++++++++++++++++++++++
2 files changed, 75 insertions(+)
diff --git a/dev/AGENTS.md b/dev/AGENTS.md
new file mode 100644
index 00000000000..947e0ac9e8e
--- /dev/null
+++ b/dev/AGENTS.md
@@ -0,0 +1,44 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update
-->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with
[DocToc](https://github.com/thlorenz/doctoc)*
+
+- [dev/ directory guidelines](#dev-directory-guidelines)
+ - [Scripts](#scripts)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# dev/ directory guidelines
+
+## Scripts
+
+New scripts in `dev/` must be standalone Python scripts (not bash). Each
script must include
+[inline script
metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/)
+placed **after** the Apache License header, so that `uv run` can execute it
without any prior
+installation:
+
+```python
+#!/usr/bin/env python3
+# Licensed to the Apache Software Foundation (ASF) ...
+# http://www.apache.org/licenses/LICENSE-2.0
+# ...
+# /// script
+# requires-python = ">=3.9"
+# dependencies = [
+# "some-package",
+# ]
+# ///
+```
+
+If the script only uses the standard library, omit the `dependencies` key but
keep the
+`requires-python` line.
+
+Run scripts with:
+
+```shell
+uv run dev/my_script.py [args...]
+```
+
+Document `uv run` (not `python`) as the invocation method in READMEs and
instructions.
diff --git a/scripts/ci/prek/AGENTS.md b/scripts/ci/prek/AGENTS.md
new file mode 100644
index 00000000000..2b36b334f73
--- /dev/null
+++ b/scripts/ci/prek/AGENTS.md
@@ -0,0 +1,31 @@
+ <!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# scripts/ci/prek/ guidelines
+
+## Overview
+
+This directory contains prek (pre-commit) hook scripts. Shared utilities live
in
+`common_prek_utils.py` — always check there before duplicating logic.
+
+## Breeze CI image scripts
+
+Some prek scripts require the Breeze CI Docker image to run (e.g. mypy checks,
OpenAPI spec
+generation, provider validation). These scripts use the
`run_command_via_breeze_shell` helper
+from `common_prek_utils.py` to execute commands inside the container.
+
+When adding a new breeze-dependent hook:
+
+1. Import and use `run_command_via_breeze_shell` from `common_prek_utils` — do
not shell out
+ to `breeze` directly.
+2. Register the hook at the **end** of the relevant `.pre-commit-config.yaml`
file (breeze
+ hooks are slow and should run after fast, local checks).
+
+## Adding new hooks
+
+- Scripts must be Python (not bash).
+- Use helpers from `common_prek_utils.py` for path constants, console output,
and breeze
+ execution.
+- Register the script in the appropriate `.pre-commit-config.yaml`
(`/.pre-commit-config.yaml`
+ for repo-wide hooks, `/airflow-core/.pre-commit-config.yaml` for
core-specific hooks, or a
+ provider-level config).
