You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@airflow.apache.org by Andrew Chang <an...@gmail.com> on 2026/10/13 16:10:22 UTC
Re: [DISCUSS] Newsfragments: when to add one
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 <ja...@potiuk.com> 於 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 <fe...@amazon.com>
> 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 <ka...@gmail.com>
> > Sent: Friday, September 11, 2026 6:44 AM
> > To: dev@airflow.apache.org <de...@airflow.apache.org>
> > 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
> >
>
Re: [DISCUSS] Newsfragments: when to add one
Posted by Pierre Jeambrun <pi...@gmail.com>.
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 <an...@gmail.com> 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 <ja...@potiuk.com> 於 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 <fe...@amazon.com>
> > 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 <ka...@gmail.com>
> > > Sent: Friday, September 11, 2026 6:44 AM
> > > To: dev@airflow.apache.org <de...@airflow.apache.org>
> > > 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
> > >
> >
>