(airflow) branch main updated: Document distributions that should never use newsfragments (#66034)

[po...@apache.org]

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 <ja...@potiuk.com>
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.