Generally +1 for the proposal. I agree that "Notable" should be the bar. I also agree that the "upper section of the release note" should be a curated minimal change set worthy of user attention.
My only hesitation concerned some of the other categories, but that is such a slippery slope, as evidenced by the prior release note. Vikram On Fri, Sep 11, 2026 at 8:52 AM Pierre Jeambrun <[email protected]> wrote: > 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 > > > > > >
