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 > > > > >
