+1 to what Kaxil wrote, and +100 for removing ambiguity and contradicting statement.
My 2c: I think the "notable" criteria should be clearer (also to make it easier for agentic workflows to decide what to do). What is considered "notable" might differ between people. I think we should be very precise—for example, specifying both when we should and when we should not use newsfragments. For example: "Only use .significant newsfragments. And only if there is something that might require separate, dedicated user action when migrating to that version of Airflow. Never add other types of newsfragments and never add them for regular bugfixes or features, especially if users installing Airflow do not have to do anything to use the feature or when the bug fix should not affect their regular workflows" Something like that—perhaps phrased better—but clarity and precision regarding when to use them and when not to use them are key. Also we should fail hard (configure towncrier in this way) to **only** allow .significant ones. Using another type should fail prek hook. Note: Dennis ... It's not that that Claude "likes" adding them. Simply our instructions - as noted by Kaxil, are contradictory and ambiguous, so when Agent get the notion about newsfragments, it gets confused - in the very same regular contributors - humans - as we would be confused IF we actually read all the instructions and try to follow them. So in this case the fact that **Claude** or whatever agent is adding them semi-randomly, is **our** fault because we were not consistent in telling the agents what to do, and it was ambiguous. J. On Sat, Sep 12, 2026 at 2:27 AM Ferruzzi, Dennis <[email protected]> wrote: > 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 >
