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 > > >
