Thanks Kaxil for bringing this to the mailing list. That's a fair assessment of the situation and indeed I think we should align on the expectations here.
I always assumed (maybe wrongly) that only things that should 'stand out' and worth users attention should go into a newsfragment. By definition that's almost always a 'significant' one. +1 for Kaxil proposal. I think that upper section of the release note should be a curated, minimal change set worth users attention. Basically I see this section as "That's what you should know / be warned about this specific airflow version. Read this before upgrading" (impactful behavioral change, migration instruction, security fixes, etc... all of them are for me 'significant'). Then the body of the release note contains the detailed list of commit for curious readers. Pierre On Fri, Sep 11, 2026 at 4:38 PM Elad Kalif <[email protected]> wrote: > my 2 cents... > Newsfragment are needed when you can't explain the change in 1 line (title > of the commit message). > Normally that goes with migration instructions or motivation why something > was changed. > > On Fri, Sep 11, 2026 at 4:44 PM Kaxil Naik <[email protected]> wrote: > > > 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 > > >
