This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new fb6752829ad Clarify when to add a newsfragment (#74589)
fb6752829ad is described below
commit fb6752829ad29aacf197deae79e0b698247d45ef
Author: Andrew Chang <[email protected]>
AuthorDate: Mon Oct 19 00:21:00 2026 +0800
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 | 6 +--
AGENTS.md | 2 +-
contributing-docs/18_contribution_workflow.rst | 59 ++++++++++++++++--------
dev/skill-evals/last-eval-hash.txt | 2 +-
4 files changed, 43 insertions(+), 26 deletions(-)
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/<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.
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_ch [...]
-- 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 [...]
+- 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 `airfl [...]
## 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
</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
----------------------
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
