FWIW, I agree they seem to be getting a bit more common than they need to be. I've also noticed that Claude really likes adding them. Perhaps worth an update to the AGENST file in parallel, once the policy is decided.
-ferruzzi ________________________________ From: Kaxil Naik <[email protected]> Sent: Friday, September 11, 2026 6:44 AM To: [email protected] <[email protected]> Subject: [EXT] [DISCUSS] Newsfragments: when to add one CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you can confirm the sender and know the content is safe. AVERTISSEMENT: Ce courrier électronique provient d’un expéditeur externe. Ne cliquez sur aucun lien et n’ouvrez aucune pièce jointe si vous ne pouvez pas confirmer l’identité de l’expéditeur et si vous n’êtes pas certain que le contenu ne présente aucun risque. Hi all, Pierre and I were discussing today whether a new feature should carry a newsfragment. We both went looking for the what our contributing doc say, neither of us found a consistent one, and we agreed that if the two of us are unsure then most of contributors too would be. So I went through what is on main and what actually reaches the release notes. 1. Only one of the six types reliably reaches users. The towncrier config declares six types. Counting their section headings across the whole of RELEASE_NOTES.rst: "Significant Changes" appears 49 times, "Improvements" 7, and "Features", "Doc only Changes" and "Misc" have never appeared once. The sections carrying the bulk of every release, New Features (10 appearances), Bug Fixes, Miscellaneous (35) and Doc Only Changes (34), are generated by dev/airflow-github changelog, which groups commits by their type: label and does not read newsfragments at all. The per-fragment view is worse. Of the already-released bugfix fragments, 19 of 21 left no trace of their own wording in the release notes; the commit subject shipped instead. Same for 16 of 17 feature fragments. significant is the only type that lands with any consistency, 11 of 20. So it feels a bugfix or feature fragment pollutes the release notes without adding anything. For those types an author writes prose that nothing consumes, and the type: label produces the line that ships. That is the reverse of the original motivation, which was that a release-note entry should be free to differ from the commit subject. 2. Our written guidance contradicts itself. contributing-docs/18_contribution_workflow.rst says "consider adding a newsfragment", lists all six types, and says a significant fragment "doesn't have to be a breaking change, it can be something that is notable but not breaking". AGENTS.md calls them "only for major or breaking changes" in one bullet and asks for one on any "user-facing" change two paragraphs later, with all six types in its example command. The prek hook checks only the filename shape and the line count, never whether the type fits or whether a fragment was warranted. Contributors guess, and coding agents guess more confidently and more often, which is how a good chunk of those 134 files got there. What I would like us to settle My preference, held loosely: - Newsfragments are for significant only: a behaviour change, a removal, a new default, a migration concern, anything someone must read before upgrading. Not breaking is fine; notable is the bar. - Everything else is classified by its type: label, which is already how those sections are built. No fragment for an ordinary bugfix, feature or doc change. - The release process prunes main. After a release, the commit where towncrier deleted the consumed fragments gets cherry-picked back, as originally intended. I am happy to sweep the 62 stale ones as a one-off. - One rule, written once, with contributing-docs and AGENTS.md pointing at it. The alternative is to keep the other five types and make the release process actually emit them, which means dropping the git-log sections and requiring a fragment on every user-facing PR. I do not think it is worth it, but I would rather we decide than keep drifting. The pruning is worth doing whichever way the types question lands, otherwise 3.4 ships with 52 entries for changes users already have. Original thread where we added Towncrier: https://lists.apache.org/thread/1bch0s4tr4w3vvxwt12z3vx0cyh0qp4o Thanks, Kaxil
