Hi All, One more "plus" to Alex's proposal:
* Files-based changelog entries can be corrected after the original PR and before the release. I believe we have a few cases where, as a feature was developing, its change log entry evolved too (I do not have the example off the top of my head, but I'm pretty sure it was real). Cheers, Dmitri. On Wed, Oct 7, 2026 at 9:33 AM Alex Dutra <[email protected]> wrote: > Hi all, > > Robert's proposal is also interesting: it keeps the discipline but > eliminates the need for changelog fragment files. But again there > might be tradeoffs to consider: > > 1) CI cannot enforce that the final commit message will contain a > valid changelog entry. > > 2) the person who merges the PR is not necessarily the PR's author, so > we would need to be careful not to override the author's changelog > text when merging. > > 3) If the PR contains many commits, GitHub by default accumulates > messages from all commits as the default merge commit message, so we > would need to be careful that unrelated text from other commits in the > PR won't show up in the changelog by mistake. > > After considering this, I think I still prefer the changelog.d approach. > > Thanks, > Alex > > On Wed, Oct 7, 2026 at 2:21 PM Jean-Baptiste Onofré <[email protected]> > wrote: > > > > Yes, that's a good idea. > > > > I'm not a big fan of the GH release ( > > > https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#example-configurations > ), > > but we can mimic a bit as Robert proposed. > > > > Regards > > JB > > > > On Wed, Oct 7, 2026 at 2:13 PM Robert Stupp <[email protected]> wrote: > > > > > I think, as an alternative, we could phrase the merged commit messages > to > > > be suitable for CHANGELOG entries. > > > Assuming we'd choose to go with conventional-commit-messages rules, a > > > relatively simple `git log` with appropriate formatting rules could be > used > > > to generate the CHANGELOG and release-notes content. > > > This would also work when commits are cherry-picked onto > release-branches, > > > and we wouldn't need to look up PR content via GItHub API requests. > > > > > > Either approach requires discipline from the PR author and/or committer > > > regarding the merged commit messages and/or PR content. > > > > > > Thoughts? > > > > > > > > > On Wed, Oct 7, 2026 at 2:03 PM Jean-Baptiste Onofré <[email protected]> > > > wrote: > > > > > > > Hi > > > > > > > > I would go with something simpler for now. > > > > > > > > 1. A PR is flagged with changelog label (in addition of the > milestone). > > > > 2. This PR contains a comment (hand written) starting with > "**CHANGELOG** > > > > ...". > > > > 3. As part of the release workflows, we create the CHANGELOG for a > > > release > > > > by assembling the **CHANGELOG** comment from PRs in the milestone > > > > > > > > No need to have AI, curated comments and assembly ad-hoc with this > > > > mechanism. > > > > > > > > Thoughts? > > > > > > > > Happy to make a draft about this :) > > > > > > > > Regards > > > > JB > > > > > > > > On Wed, Oct 7, 2026 at 1:11 PM Alex Dutra <[email protected]> wrote: > > > > > > > > > Hi all, > > > > > > > > > > As I recall, the main reason for maintaining a manually curated > > > > > changelog was to offer a clear, thoughtful summary of release > changes > > > > > – a task that automated tools traditionally struggled with. > > > > > > > > > > With recent advancements in AI, we could consider revisiting this > > > > > stance and exploring an AI-assisted workflow, as Yufei proposed. > > > > > > > > > > That said, I think we should consider these tradeoffs carefully > before > > > > > making such a decision: > > > > > > > > > > - Missing context: the most essential parts of our changelogs are > the > > > > > highlights and upgrade notes, e.g. the rolling-upgrade caveat for > > > > > credentialVendingMechanism. Since details like this aren't > captured in > > > > > PR titles or code diffs, an LLM model can only include them if an > > > > > author explicitly documented them somewhere. > > > > > > > > > > - Silent omissions: if an LLM accidentally omits a breaking change, > > > > > the resulting output still appears plausible, making it difficult > for > > > > > a release manager to identify what's missing. > > > > > > > > > > - Non-deterministic output: because LLM-generated text isn't > directly > > > > > reproducible from the repository state, every execution produces a > > > > > slightly different changelog, which could be an issue for official > > > > > release votes. > > > > > > > > > > Given these points, requiring PR authors to submit changelog > entries > > > > > when relevant remains imho a valuable discipline. > > > > > > > > > > Moving to a changelog.d directory structure should effectively > address > > > > > the pain around merge conflicts and reduce contention on > CHANGELOG.md. > > > > > > > > > > Thanks, > > > > > Alex > > > > > > > > > > On Tue, Oct 6, 2026 at 8:18 PM Dmitri Bourlatchkov < > [email protected]> > > > > > wrote: > > > > > > > > > > > > Hi All, > > > > > > > > > > > > When I originally proposed the CHANGELOG file [1], the idea was > to > > > help > > > > > > with itemizing the changes at release time :) > > > > > > > > > > > > It was never meant to include an entry for every small PR, only > for > > > PRs > > > > > > worth mentioning in release notes. > > > > > > > > > > > > Alex's idea of "/changelog.d" sounds interesting. I suppose if we > > > name > > > > > > those files according to to the date, we'll automatically get a > > > sorted > > > > > > change log for release notes. We could probably also use a > pattern or > > > > > > textual tags to identify breaking changes, fixes, etc. > > > > > > > > > > > > Re: conflict resolution via UI, I think a tool plus some PR > > > discipline > > > > is > > > > > > preferable to a manual process. > > > > > > > > > > > > [1] > https://lists.apache.org/thread/qznf8toht1r7ml35lt4p8nwlk9op638v > > > > > > > > > > > > Cheers, > > > > > > Dmitri. > > > > > > > > > > > > On Tue, Oct 6, 2026 at 1:35 PM Jean-Baptiste Onofré < > [email protected] > > > > > > > > > wrote: > > > > > > > > > > > > > Hi, > > > > > > > > > > > > > > To play devil's advocate: do we really need a CHANGELOG file? > :) > > > > > > > > > > > > > > I agree that we need to inform users about breaking changes and > > > > > user-facing > > > > > > > updates. However, we could simply use a "breaking-change" > label on > > > > > GitHub > > > > > > > PRs and automatically populate the Release Notes at release > time, > > > > > rather > > > > > > > than manually maintaining a CHANGELOG. The remainder of a > typical > > > > > CHANGELOG > > > > > > > is essentially just a git log, which most users do not read > > > anyway. I > > > > > have > > > > > > > successfully used this approach across several ASF projects. > > > > > > > > > > > > > > Thoughts? > > > > > > > > > > > > > > Regards, > > > > > > > JB > > > > > > > > > > > > > > > > > > > > > On Tue, Oct 6, 2026 at 7:08 PM Ayush Saxena < > [email protected]> > > > > > wrote: > > > > > > > > > > > > > > > Hi Everyone, > > > > > > > > +1 on trying to find some way around solving CHANGELOG > conflicts. > > > > > Some > > > > > > > > numbers in case they help make the case: over the last 60 > days, > > > 75 > > > > of > > > > > > > > 339 commits on main touched CHANGELOG.md — roughly one in > four > > > and > > > > a > > > > > > > > half. Every one of those is a potential conflict with every > > > other, > > > > > and > > > > > > > > none of them is a real logical conflict. > > > > > > > > > > > > > > > > On Yufei's two points: > > > > > > > > > > > > > > > > ASF headers — I don't think fragments need them. rat already > has > > > an > > > > > > > > exclusion list in build.gradle.kts (the RatTask block around > line > > > > > 55), > > > > > > > > and it already excludes a Markdown file on exactly these > grounds: > > > > > > > > .github/pull_request_template.md. Adding changelog.d/** is > one > > > > line. > > > > > > > > Worth double checking though — but they never ship in a > release > > > > > > > > artifact, since they're consumed and deleted before the RC is > > > cut, > > > > so > > > > > > > > I think ASF header isn't required. > > > > > > > > > > > > > > > > Multi-PR features — this gets easier rather than harder. > Today a > > > > > > > > follow-up has to edit shared lines in CHANGELOG.md; with > > > fragments > > > > it > > > > > > > > edits or deletes one file its own feature owns, so follow-ups > > > stop > > > > > > > > colliding with unrelated work. > > > > > > > > > > > > > > > > One thing worth settling in the PR: > > > > > > > > > > > > > > > > Naming. changelog.d/pr-1235.md has a chicken-and-egg > problem: you > > > > > > > > don't know the PR number until the PR exists, so the first > push > > > > never > > > > > > > > has the right name. Allowing a short slug > > > > > > > > (changelog.d/ranger-implied-grants.md), or keying off the > issue > > > > > number > > > > > > > > where one exists, avoids the extra round trip. towncrier's > > > > convention > > > > > > > > is <issue>.<type>.md with a +<slug>.md escape hatch for > changes > > > > with > > > > > > > > no issue. > > > > > > > > > > > > > > > > Robert's point changes my view somewhat. If resolving in the > UI > > > > > > > > doesn't dismiss the approval, the per-conflict cost is much > lower > > > > > than > > > > > > > > I assumed. The one cost it does leave is CI: that merge > commit > > > > > re-runs > > > > > > > > the entire pipeline for a one-line docs change.This mostly > should > > > > be > > > > > > > > solvable, that we don't trigger the entire CI flow when the > > > change > > > > is > > > > > > > > only in the CHANGELOG. With that plus a line in the PR > template > > > > about > > > > > > > > resolving in the UI, I think the lighter option is a genuine > > > > > > > > alternative to the fragment directory rather than just a > stopgap. > > > > > > > > > > > > > > > > -Ayush > > > > > > > > > > > > > > > > On Tue, 6 Oct 2026 at 22:23, Robert Stupp <[email protected]> > > > wrote: > > > > > > > > > > > > > > > > > > CHANGELOG.md entries are usually resolvable via the GH UI. > > > > > > > > > > > > > > > > > > I did that today and it only required removing three Git > > > conflict > > > > > > > marker > > > > > > > > > lines in total. That ended in a "merge" commit generated > by GH > > > > that > > > > > > > > didn't > > > > > > > > > even require another approval of the PR. > > > > > > > > > > > > > > > > > > On Tue, Oct 6, 2026 at 6:41 PM Yufei Gu < > [email protected]> > > > > > wrote: > > > > > > > > > > > > > > > > > > > Hi Alex, > > > > > > > > > > > > > > > > > > > > Thanks for raising this point, it is definitely a pain > point. > > > > > > > > > > > > > > > > > > > > To address it, I think we could create a file named > after the > > > > PR > > > > > > > > number, > > > > > > > > > > such as changelog.d/pr-1235.md. > > > > > > > > > > > > > > > > > > > > A few overhead items and concerns to consider: > > > > > > > > > > > > > > > > > > > > 1. ASF Headers: New files will require ASF headers. > While > > > this > > > > > is a > > > > > > > > bit > > > > > > > > > > verbose, it should be fine. > > > > > > > > > > 2. Multi-PR Features: We may need to update the > changelog > > > > when a > > > > > > > > feature > > > > > > > > > > is split across multiple small PRs. We could allow > follow-up > > > > PRs > > > > > to > > > > > > > > modify > > > > > > > > > > or even remove the changelog entry created by a previous > PR. > > > It > > > > > > > should > > > > > > > > be > > > > > > > > > > fine as well. > > > > > > > > > > > > > > > > > > > > I'm open to other ideas as well. > > > > > > > > > > > > > > > > > > > > Yufei > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > On Tue, Oct 6, 2026 at 9:05 AM Alex Dutra < > [email protected] > > > > > > > > > wrote: > > > > > > > > > > > > > > > > > > > > > Hi all, > > > > > > > > > > > > > > > > > > > > > > Almost every PR that touches user-facing behavior adds > an > > > > entry > > > > > > > under > > > > > > > > > > > "## [Unreleased]" in CHANGELOG.md. Since all of those > PRs > > > > edit > > > > > the > > > > > > > > > > > same few lines, they regularly conflict with each > other. > > > > > > > Contributors > > > > > > > > > > > and reviewers then spend time rebasing and > re-resolving a > > > > file > > > > > that > > > > > > > > > > > has no real logical conflicts. > > > > > > > > > > > > > > > > > > > > > > I'd like to propose a process change that removes this > > > > problem: > > > > > > > > > > > instead of editing CHANGELOG.md directly, each PR adds > its > > > > own > > > > > > > small > > > > > > > > > > > file under a new changelog.d/ directory. Because two > PRs > > > > never > > > > > edit > > > > > > > > > > > the same file, they can't conflict. At release time, a > > > script > > > > > > > > > > > assembles the fragments into CHANGELOG.md and deletes > them. > > > > > > > > > > > > > > > > > > > > > > What do you think? If you like the idea, I can draft a > PR > > > and > > > > > flesh > > > > > > > > > > > out the details. > > > > > > > > > > > > > > > > > > > > > > Thanks, > > > > > > > > > > > Alex > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
