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 f5a2f0e359c Document distributions that should never use newsfragments
(#66034)
f5a2f0e359c is described below
commit f5a2f0e359c74f17152101fed46b8f03ea4470a5
Author: Jarek Potiuk <[email protected]>
AuthorDate: Tue Apr 28 19:26:13 2026 +0200
Document distributions that should never use newsfragments (#66034)
providers/ and airflow-ctl/ are both released from main and their release
managers regenerate the changelog from git log — so per-PR newsfragments
are not consumed. Document this in AGENTS.md (root) and providers/AGENTS.md,
and clarify that newsfragments are only used by towncrier-managed
distributions (airflow-core, chart, dev/mypy). Point provider PRs at
docs/changelog.rst and airflow-ctl PRs at RELEASE_NOTES.rst.
---
AGENTS.md | 6 ++++--
providers/AGENTS.md | 14 ++++++++++++++
2 files changed, 18 insertions(+), 2 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index f960cd36537..22ca4d1c79b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -123,7 +123,7 @@ reported as such are described in "What is NOT considered a
security vulnerabili
- Guard heavy type-only imports (e.g., `kubernetes.client`) with
`TYPE_CHECKING` in multi-process code paths.
- Define dedicated exception classes or use existing exceptions such as
`ValueError` instead of raising the broad `AirflowException` directly. Each
error case should have a specific exception type that conveys what went wrong.
- Apache License header on all new files (prek enforces this).
-- Newsfragments are only added if a major change or breaking change is
applied. This is usually coordinate during review. Please do not add
newsfragments per default as in most cases this needs a reversion during review.
+- 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 (usually coordinated during review; do not add by 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 newsfragm [...]
## Testing Standards
@@ -146,9 +146,11 @@ Write commit messages focused on user impact, not
implementation details.
- **Good:** `UI: Fix Grid view not refreshing after task actions`
- **Bad:** `Initialize DAG bundles in CLI get_dag function`
-Add a newsfragment for user-visible changes:
+For `airflow-core` (and `chart/`, `dev/mypy/`) user-visible changes, add a
newsfragment in that distribution's `newsfragments/` directory:
`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.
+
- NEVER add Co-Authored-By with yourself as co-author of the commit. Agents
cannot be authors, humans can be, Agents are assistants.
### Git remote naming conventions
diff --git a/providers/AGENTS.md b/providers/AGENTS.md
index 71278fdde78..254c8df7436 100644
--- a/providers/AGENTS.md
+++ b/providers/AGENTS.md
@@ -17,3 +17,17 @@ Each provider is an independent package with its own
`pyproject.toml`, tests, an
- Don't upper-bound dependencies by default; add limits only with
justification.
- Tests live alongside the provider — mirror source paths in test directories.
- Full guide:
[`contributing-docs/12_provider_distributions.rst`](../contributing-docs/12_provider_distributions.rst)
+
+## Changelog — never use newsfragments
+
+**Never create newsfragments for providers.** Providers are released from
`main` in waves, so
+per-PR newsfragments are not consumed by the release process — the release
manager regenerates the
+changelog from `git log`. The towncrier-managed `newsfragments/` workflow is
used only by
+`airflow-core/`, `chart/`, and `dev/mypy/`. (`airflow-ctl/` follows the same
"no newsfragments,
+direct edit" pattern as providers — see `dev/README_RELEASE_AIRFLOWCTL.md`.)
+
+When a provider change needs a user-visible note (typically a breaking change
or important behavior
+change that warrants explanation), update the provider's `docs/changelog.rst`
directly in the same
+PR, just below the `Changelog` header — exactly as the in-file `NOTE TO
CONTRIBUTORS` block
+describes. Routine entries (features, bug fixes, misc) are collected
automatically by the release
+manager from commit messages, so most PRs do not need to touch the changelog
at all.
