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 >
