potiuk opened a new pull request, #68116: URL: https://github.com/apache/airflow/pull/68116
Selective checks (`dev/breeze/src/airflow_breeze/utils/selective_checks.py`) drive what CI runs for every PR, push and canary, but until now the documentation was a flat reference list — it didn't explain *why* the system behaves the way it does or how to reason about it when a run does more than expected. This PR expands [`dev/breeze/doc/ci/04_selective_checks.md`](https://github.com/apache/airflow/blob/main/dev/breeze/doc/ci/04_selective_checks.md) with: - **The optimisation goal and design assumptions** — changed files as a risk proxy, conservative-when-in-doubt (always fall back to the full matrix rather than risk correctness), and "trust earned on `main`" (the canary backstops aggressive PR-time skipping). - **A mental model** — inputs → run mode (`full_tests_needed` / `all_versions` / `is_canary_run`) → file-group matches → GitHub Actions outputs, with the `_should_be_run` helper that ties it together. - **Mermaid diagrams** for the decision pipeline: run-mode selection, the `full_tests_needed` short-circuit ladder, mode → which jobs run, and test-type selection — showing the *sequence* of rules and how each impacts which part of CI executes. - **A "rules are simple individually" table** mapping concrete file changes to their effect. - **Worked examples** for pull requests, pushes to `main`, pushes to release branches, and scheduled canary runs — making the differences between event types concrete. - **A troubleshooting section** ("my CI run does too much") — how to read the `[warning]` reasons in the selective-checks job output, reproduce locally with `breeze selective-checks --commit-ref`, and the usual escalation triggers. It also refreshes the existing decision-rules list to match current behaviour (release-branch and only-text PUSH exceptions, API-contract vs API-source distinction), and adds an `AGENTS.md` rule requiring `selective_checks.py` and this doc to be updated together. Docs-only change. --- ##### Was generative AI tooling used to co-author this PR? - [X] Yes — Claude Code (Opus 4.8 1M) Generated-by: Claude Code (Opus 4.8 1M) following [the guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions) -- 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]
