diff --git a/.agents/skills/airflow-pr-draft-summary/SKILL.md b/.agents/skills/airflow-pr-draft-summary/SKILL.md index 780f6c82b96..4435ea18859 100644 --- a/.agents/skills/airflow-pr-draft-summary/SKILL.md +++ b/.agents/skills/airflow-pr-draft-summary/SKILL.md @@ -55,10 +55,8 @@ The commit message **body** should describe **why** the change is made — the m context — and **never what** the change is. The diff already shows what changed; restating it in prose adds noise. -For `airflow-core` (and `chart/`, `dev/mypy/`) **user-facing** changes, add a newsfragment in that distribution's `newsfragments/` directory. **Golden rule: only add a newsfragment when you are certain the change is visible to users; when in doubt, do not add one** — a maintainer will request one in review if it is needed. Build/release tooling, CI, packaging, internal refactors, and dev-only scripts are not user-facing and must not get a newsfragment: -`echo "Brief description" > airflow-core/newsfragments/{PR_NUMBER}.{bugfix|feature|improvement|doc|misc|significant}.rst` - -**Do not add newsfragments for `providers/` or `airflow-ctl/`** — their release managers regenerate the changelog from `git log` and do not consume newsfragments. Update the changelog directly when needed: `providers//docs/changelog.rst` (see `providers/AGENTS.md`) or `airflow-ctl/RELEASE_NOTES.rst`. Changes to `task-sdk/` use `airflow-core/newsfragments/` since task-sdk ships in airflow-core. +Follow the newsfragment rules in root `AGENTS.md` (full text in `contributing-docs/18_contribution_workflow.rst`). When an `airflow-core` change does need one: +`echo "Brief description" > airflow-core/newsfragments/{PR_NUMBER}.significant.rst` - NEVER add Co-Authored-By with yourself as co-author of the commit. Agents cannot be authors, humans can be, Agents are assistants. diff --git a/AGENTS.md b/AGENTS.md index 7685fb036af..fd8b64b293b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -153,7 +153,7 @@ reported as such are described in "What is NOT considered a security vulnerabili - Name functions and methods with action verbs: `get_`, `extract_`, `find_`, `compute_`, `build_`, etc. Avoid noun-only names like `_serialize_keys` or `_base_names` — they read as attributes, not callables. Predicates (`is_`, `has_`) are the one exception. - Apache License header on all new files (prek enforces this). - **Keep selective-checks behaviour and its documentation in sync.** The CI optimisation logic lives in `dev/breeze/src/airflow_breeze/utils/selective_checks.py` (run-mode decisions, file-group matching, test-type selection, prek-hook skipping). Whenever you change a rule there — add/rename a file group, change what forces `full_tests_needed`/`all_versions`, alter how providers or test types are selected, or change which prek hooks are skipped — update [`dev/breeze/doc/ci/04_selective_checks.md`](dev/breeze/doc/ci/04_selective_checks.md) in the same PR (the decision-rules list, the diagrams, the outputs table, and the worked examples as applicable) and add/adjust tests in `dev/breeze/tests/test_selective_checks.py`. The doc is the human-facing explanation of that file; letting them drift makes CI behaviour impossible to reason about. -- Newsfragments are only used by distributions whose release process consumes them via towncrier — currently `airflow-core/newsfragments/`, `chart/newsfragments/`, and `dev/mypy/newsfragments/` — and only for major or breaking changes. **Golden rule: never create a newsfragment unless you are certain the change is user-facing.** If you are not sure the change is visible to users — build/release tooling, CI, packaging, internal refactors with no behavior change, dev-only scripts, and test-only changes are *not* user-facing — do **not** add one. Default to omitting it; a maintainer will ask for a newsfragment during review if the change warrants one. Adding a spurious newsfragment for a non-user-facing change is a defect, not a safe default. **Never add newsfragments for `providers/` or `airflow-ctl/`** — those distributions are released from `main` and their release managers regenerate the changelog from `git log`, so per-PR newsfragments are not consumed (see `dev/README_RELEASE_PROVIDERS.md` and `dev/README_RELEASE_AIRFLOWCTL.md`). For a user-visible note in those distributions, edit the changelog directly: `providers//docs/changelog.rst` for providers, `airflow-ctl/RELEASE_NOTES.rst` for airflow-ctl. Changes to `task-sdk/` ship in `airflow-core` — use `airflow-core/newsfragments/`. +- Newsfragments: the full rules are in [`contributing-docs/18_contribution_workflow.rst`](contributing-docs/18_contribution_workflow.rst#newsfragments). Do not add one by default. In `airflow-core/` use only `significant` newsfragments, and only for a change users must read before upgrading: a behavior change, a removal or a new default, or migration steps. `task-sdk/` has no release notes of its own (its changes are listed in the Airflow release notes), so its newsfragments go in `airflow-core/newsfragments/`. Never add one for an ordinary bug fix, feature, improvement or doc change, or for build/release tooling, CI, packaging, internal refactors, dev-only scripts and tests. In `chart/`, add one only for major or breaking changes. When unsure, leave it out: a maintainer will ask for one during review if it is needed. **Never add newsfragments for `providers/` or `airflow-ctl/`**. Their release managers regenerate the changelog from `git log` (see `dev/README_RELEASE_PROVIDERS.md` and `dev/README_RELEASE_AIRFLOWCTL.md`). For a user-visible note there, edit `providers//docs/changelog.rst` or `airflow-ctl/RELEASE_NOTES.rst` directly. ## Testing Standards diff --git a/contributing-docs/18_contribution_workflow.rst b/contributing-docs/18_contribution_workflow.rst index 86181a11043..b96f4f16238 100644 --- a/contributing-docs/18_contribution_workflow.rst +++ b/contributing-docs/18_contribution_workflow.rst @@ -187,26 +187,10 @@ Step 4: Prepare PR * Run the appropriate tests as described in `Testing documentation <09_testing.rst>`__. - * Consider adding a newsfragment to your PR so you can add an entry in the release notes. - The following newsfragment types are supported: - - * `significant` - * `feature` - * `improvement` - * `bugfix` - * `doc` - * `misc` - - To add a newsfragment, create an ``rst`` file named ``{pr_number}.{type}.rst`` (e.g. ``1234.bugfix.rst``) - and place in either `airflow-core/newsfragments `__ for core newsfragments, - or `chart/newsfragments `__ for helm chart newsfragments. - - In general newsfragments must be one line. For newsfragment type ``significant``, you may include summary and body separated by a blank line, similar to ``git`` commit messages. - One thing to note here is that a ``significant`` newsfragment doesn't have to be a breaking change, it can be something that is notable but not breaking. - - A CI check validates that newsfragment filenames use the correct PR number. If you need to skip - this check (e.g. when cherry-picking a newsfragment from another PR), add the - ``skip newsfragment check`` label to your PR. + * Check whether your PR needs a newsfragment. Most PRs do not: the release notes for ordinary bug fixes, + features and doc changes are built from the commit title. Add one only for a change users must read + before upgrading, such as a behaviour change, a removal, a new default or migration steps. A maintainer + will ask if your PR needs one. See `Newsfragments`_ below for the details. 2. Rebase your fork, squash commits, and resolve all conflicts. See `How to rebase PR <10_working_with_git.rst#how-to-rebase-pr>`_ if you need help with rebasing your change. Remember to rebase often if your PR takes a lot of time to @@ -244,6 +228,41 @@ Step 4: Prepare PR they want to get it reviewed and merged. +Newsfragments +~~~~~~~~~~~~~ + +Newsfragments are only consumed by ``airflow-core/``, ``chart/`` and ``dev/mypy/``. Do not add one by default. + +For ``airflow-core/``, use only ``significant`` newsfragments, and only for a change users must read before +upgrading: + +* a behaviour change, a removal or a new default, +* a change that needs migration steps. + +``task-sdk/`` has no release notes of its own. Its changes are listed in the Airflow release notes, so put +newsfragments for ``task-sdk/`` changes in ``airflow-core/newsfragments/``. + +A ``significant`` newsfragment does not have to be a breaking change. Do not add a newsfragment for an +ordinary bug fix, feature, improvement or documentation change, or for internal refactors, CI, tooling and +tests. For ``chart/``, add a newsfragment only for major or breaking changes. + +If you are unsure, leave it out. A maintainer will ask for one during review if it is needed. + +Never add newsfragments for ``providers/`` or ``airflow-ctl/``: their release managers regenerate the +changelog from the commit history. For a user-visible note, edit the changelog directly: the provider's +``docs/changelog.rst`` (see `providers/AGENTS.md `__) +or ``airflow-ctl/RELEASE_NOTES.rst``. + +To add a newsfragment, create an ``rst`` file named ``{pr_number}.significant.rst`` (e.g. ``1234.significant.rst``) +and place it in `airflow-core/newsfragments `__ for core newsfragments, or +`chart/newsfragments `__ for helm chart newsfragments. It can be a single line, or a +summary and a body separated by a blank line, similar to ``git`` commit messages. + +A CI check validates that newsfragment filenames use the correct PR number. If you need to skip this check +(e.g. when cherry-picking a newsfragment from another PR), add the ``skip newsfragment check`` label to +your PR. + + Step 5: Pass PR Review ---------------------- diff --git a/dev/skill-evals/last-eval-hash.txt b/dev/skill-evals/last-eval-hash.txt index 451e4d1e3d4..75a3c2c4d54 100644 --- a/dev/skill-evals/last-eval-hash.txt +++ b/dev/skill-evals/last-eval-hash.txt @@ -1,3 +1,3 @@ # Generated by dev/skill-evals/eval.py — do not edit or resolve conflicts by hand. # Run `prek run run-skill-eval --hook-stage manual --all-files` to regenerate. -d0e8ed3ebe9973449495c65634f02bfe2fb1a41e38bb4a09aa7d0199502b3f72 +6a82b68ab3d4179b148c7a545206c4e37e7611f85e9b830d89186a8713c8b272