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 c1d99ec54cd Add golden rule: do not create newsfragments unless
certain a change is user-facing (#67982)
c1d99ec54cd is described below
commit c1d99ec54cddde1cb4b7214f0cd0b6ab6cb2bb10
Author: Jarek Potiuk <[email protected]>
AuthorDate: Thu Jun 4 15:33:48 2026 +0200
Add golden rule: do not create newsfragments unless certain a change is
user-facing (#67982)
Agents (and contributors) have been adding newsfragments for changes that
are not user-facing — build/release tooling, CI, internal refactors —
which then have to be removed in review. Make the expectation explicit: a
newsfragment is only for changes certainly visible to users; when in
doubt, omit it and let a maintainer request one during review.
---
AGENTS.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index f817645efd8..f3dde9cbd07 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -141,7 +141,7 @@ reported as such are described in "What is NOT considered a
security vulnerabili
- Bulk `DELETE`/`UPDATE` in the scheduler loop or any synchronous interval
task (e.g. `call_regular_interval` callbacks) must be batched with `LIMIT` and
committed between batches — never issue a single unbounded bulk write against a
user-driven table. Unbounded bulk writes hold row locks for the entire
transaction (blocking concurrent writers) and stall the scheduler main loop.
Filter columns used by the cleanup must be indexed. Follow the batching pattern
in `airflow-core/src/airflow/u [...]
- 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).
-- 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 [...]
+- 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 [...]
## Testing Standards
@@ -164,7 +164,7 @@ 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`
-For `airflow-core` (and `chart/`, `dev/mypy/`) user-visible changes, add a
newsfragment in that distribution's `newsfragments/` directory:
+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.
