JB has a good point! +1 on either removing the changelog file or NOT enforcing a changelog for every PR while still keeping track of breaking changes.
For non-breaking changes, an agent could summarize the PR content during the release process, which we can then review before release. What do you think? Yufei On Tue, Oct 6, 2026 at 10:35 AM 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 > > > > > > > > > > > >
