Hi All, >From my POV (as a PR reviewer), editing the merge commit message is a heavy overhead.
Small PRs with one or two commits are usually not a problem, but after a week of back-and-forth review-based changes, editing the commit message becomes a nightmare. However, the idea of keeping CHANGELOG entries in commits sounds workable to me. I'd propose for PR authors to provide the CHANGELOG as a part of the PR description (not part of individual commits on a branch): * Easily visible for all reviewers * Easy to adjust as the review progresses (in complex cases). * Easy to copy (edit) into the merge commit message. That said, my personal preference is still with /changelod.d (Alex's proposal) * It is probably just as easy for tools / AI to process as commit messages * It will carry over into cherry-picks * Change log text does go through a mechanical but manual edit phase (during cherry pick or merge) * In a PR, the change log entry (file) can be adjusted in multiple commits without adding extra merge work or inconvenience. * In a PR, Change log entry comments can be made via normal GH UI archored to specific lines. Cheers, Dmitri. On Wed, Oct 7, 2026 at 8:13 AM 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 > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
