Clarify when to add a newsfragment (#74589)

* Clarify when to add a newsfragment

The contribution guide, AGENTS.md and the PR drafting skill each had
their own newsfragment rule, and they disagreed: the guide encouraged
adding one of six types, AGENTS.md said "major or breaking" but also
asked for one on any user-facing change. The dev@ thread "[DISCUSS]
Newsfragments: when to add one" proposed significant-only fragments
for airflow-core, no fragment for an ordinary bug fix, feature or doc
change, and one rule written once with AGENTS.md pointing at it.

* Tighten the newsfragment criteria after review

task-sdk has no release notes of its own, its changes are listed in
the Airflow release notes, which is why its newsfragments go to
airflow-core. A change that is neither a behaviour change nor needs
migration steps does not need a newsfragment, and listing every
towncrier type invited using the ones the rule excludes.

.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/<provider>/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.
 

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/<provider>/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/<provider>/docs/changelog.rst` or `airflow-ctl/RELEASE_NOTES.rst` directly.
 
 ## Testing Standards
 

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 </airflow-core/newsfragments>`__ for core newsfragments,
-     or `chart/newsfragments </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 </providers/AGENTS.md#changelog--never-use-newsfragments>`__)
+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 </airflow-core/newsfragments>`__ for core newsfragments, or
+`chart/newsfragments </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
 ----------------------
 

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