Thanks for the follow up Andrew. I'll propose a lazy consensus to register this formally.
We can follow up on the PR directly. On Tue, Oct 13, 2026 at 6:13 PM Andrew Chang <[email protected]> wrote: > Hi, > > I noticed that agents keep adding newsfragments… So I tried to summarize > the discussion in this thread and turned it into a PR: > > https://github.com/apache/airflow/pull/74589 > > Ash already made some suggestions (Thanks Ash!) > Would appreciate some more opinions on this to make it accurate. > > Thanks, > Andrew > > Jarek Potiuk <[email protected]> 於 2026年9月12日週六 下午7:18寫道： > > > +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 > > > > > >
