diff --git a/.agents/skills/airflow-publish-changes/SKILL.md b/.agents/skills/airflow-publish-changes/SKILL.md index cc4fe94beb793..8f115bea26fcd 100644 --- a/.agents/skills/airflow-publish-changes/SKILL.md +++ b/.agents/skills/airflow-publish-changes/SKILL.md @@ -115,7 +115,7 @@ code review checklist in [`.github/instructions/code-review.instructions.md`](.. and fix any failures. The skipped hooks start long-running local servers or provision the opt-in Codex environment rather than run checks that complete. 6. Run relevant individual tests and confirm they pass. -7. Find which tests to run for the changes with selective-checks and run those tests in parallel to confirm they pass and check for CI-specific issues. +7. Run `breeze verify` and execute every command it lists. The list comes from the same selective-checks logic CI uses. `breeze verify --full` shows everything CI runs for the default matrix cell, including the full suite CI adds when a change touches CI tooling or dependency files. Static checks are not listed: steps 4 and 5 cover them. Confirm the commands pass and check for CI-specific issues. 8. Check for security issues — no secrets, no injection vulnerabilities, no unsafe patterns. Before pushing, always rebase your branch onto the latest target branch (usually `main`) diff --git a/AGENTS.md b/AGENTS.md index f7a6a9b5fb7c2..7685fb036af01 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,6 +54,7 @@ Don't spell out **Directed Acyclic Graph** except for historical context. - **Run regular (fast) static checks:** `prek run --from-ref --stage pre-commit` - **Run manual (slower) checks:** `prek run --from-ref --stage manual --skip compile-ui-assets-dev --skip view-skill-eval --skip run-skill-eval-codex` (the skipped hooks start long-running local servers or provision the opt-in Codex environment rather than run checks that complete) - **Build docs:** `breeze build-docs` +- **List the local verification for your changes:** `breeze verify` (add `--full` for everything CI runs for the default matrix cell except static checks, `--json` for machine-readable output). It uses the same selective-checks logic as CI. - **Determine which tests to run based on changed files:** `breeze ci selective-check --commit-ref ` diff --git a/contributing-docs/08_static_code_checks.rst b/contributing-docs/08_static_code_checks.rst index 9bae6b9248fb2..9c34dfd16b110 100644 --- a/contributing-docs/08_static_code_checks.rst +++ b/contributing-docs/08_static_code_checks.rst @@ -236,6 +236,7 @@ To check other usage types of the pre-commit framework, see `Pre-commit website - "- **Run regular (fast) static checks:** `prek run --from-ref --stage pre-commit`" - "- **Run manual (slower) checks:** `prek run --from-ref --stage manual --skip compile-ui-assets-dev --skip view-skill-eval --skip run-skill-eval-codex` (the skipped hooks start long-running local servers or provision the opt-in Codex environment rather than run checks that complete)" - "- **Build docs:** `breeze build-docs`" + - "- **List the local verification for your changes:** `breeze verify` (add `--full` for everything CI runs for the default matrix cell except static checks, `--json` for machine-readable output). It uses the same selective-checks logic as CI." - "- **Determine which tests to run based on changed files:** `breeze ci selective-check --commit-ref `" .. AGENT-SKILL-END diff --git a/dev/breeze/doc/03_developer_tasks.rst b/dev/breeze/doc/03_developer_tasks.rst index 56b8bbbb8ba76..b94b4b017272f 100644 --- a/dev/breeze/doc/03_developer_tasks.rst +++ b/dev/breeze/doc/03_developer_tasks.rst @@ -316,6 +316,61 @@ If the provider name is ``apache-airflow-providers-cncf-kubernetes``, it will be Note: For building docs for apache-airflow-providers index, use ``apache-airflow-providers`` as the short hand operator. +Finding out what CI will run for your change +-------------------------------------------- + +``breeze verify`` reads the files changed against the target branch (the merge-base of +``--base-ref`` and ``HEAD``, plus untracked files), runs the same selective-checks logic CI uses +and lists the commands to run locally for the change. Nothing is executed. The only non-zero exit +is a usage error such as a base ref git cannot resolve. + +By default ``--base-ref`` is ``main`` on the git remote that points at apache/airflow (``upstream`` +if several do), the same base GitHub compares a PR with. A local ``main`` that is behind the +``main`` your branch has merged would count every merged-in commit as your change. Without such a +remote, ``breeze verify`` falls back to the local ``main`` branch and says so. It also warns when +the branch has merged commits the base does not have, for example after GitHub's "Update branch" +when the remote was not fetched since. With ``--json`` the warnings go to stderr. + +.. code-block:: bash + + breeze verify + breeze verify --json + breeze verify --full + breeze verify --base-ref main + +Each row says what kind of check it is, whether it runs on the host or needs Docker and the +CI image (``breeze``), and the exact command. Jobs CI runs on every PR regardless of the change +(breeze's own unit tests, the shared distributions) only show up with ``--full``. The translation +check is never listed: CI runs it with ``|| true``, so it cannot fail a PR. +Static checks are not listed either: ``prek`` already picks the hooks to run for the changed files, +so run it as usual. The exception is the ``mypy-providers`` and ``migration-round-trip`` hooks, +which CI runs but a default ``prek install`` does not (they are ``pre-push`` or ``manual`` stage +hooks). When the change triggers them, ``breeze verify`` prints the +``prek run --stage manual --from-ref `` command to run each one, and ``--json`` +lists them under ``manual_prek_hooks``. +Use ``--json`` for machine-readable output with the same fields. + +When a change touches CI tooling or dependency files, selective checks make CI run the full suite. +The default list leaves that expansion out and only shows what the changed files match themselves, +with a note that CI will run more. ``--full`` lists everything CI runs for the default matrix cell +(default Python, sqlite), apart from static checks. + +Even ``--full`` is not the full CI matrix. Other Python versions, Postgres and MySQL, +lowest-dependency runs, Kubernetes, Helm, e2e suites, the provider compatibility matrix and ARM +runners only run in CI. Two more caveats. Selective checks compare ``pyproject.toml`` contents +between ``HEAD`` and ``HEAD^`` only, so dependency changes that are uncommitted or in earlier +commits of your branch are not detected as such (test selection is unaffected, only the +dependency-bump checks are). Packaging steps CI runs around some tests (building and +twine-checking the Task SDK and airflow-ctl wheels, regenerating the Python API client from its +own repository) are not listed. + +These are all available flags of ``verify`` command: + +.. image:: ./images/output_verify.svg + :target: https://raw.githubusercontent.com/apache/airflow/main/dev/breeze/images/output_verify.svg + :width: 100% + :alt: Breeze verify + Running static checks --------------------- diff --git a/dev/breeze/doc/ci/04_selective_checks.md b/dev/breeze/doc/ci/04_selective_checks.md index f4f0ce8badf03..5d96ed6d91014 100644 --- a/dev/breeze/doc/ci/04_selective_checks.md +++ b/dev/breeze/doc/ci/04_selective_checks.md @@ -50,6 +50,11 @@ contributors in case of simpler changes. > [`dev/breeze/src/airflow_breeze/utils/selective_checks.py`](../../src/airflow_breeze/utils/selective_checks.py). > When you change that file, **update this document in the same PR** so the behaviour and the > documentation stay in sync. +> +> `breeze verify` maps the `run_*` flags to local commands in +> [`dev/breeze/src/airflow_breeze/utils/verification_plan.py`](../../src/airflow_breeze/utils/verification_plan.py). +> Adding a `run_*` flag to `SelectiveChecks` also means classifying it there; +> `dev/breeze/tests/test_verification_plan.py` fails until you do. ## Why selective checks exist (the optimisation goal) diff --git a/dev/breeze/doc/images/output-commands.svg b/dev/breeze/doc/images/output-commands.svg index 13418f6e0a673..e6405bcad55fb 100644 --- a/dev/breeze/doc/images/output-commands.svg +++ b/dev/breeze/doc/images/output-commands.svg @@ -1,4 +1,4 @@ - +