Hi all, +1 on Yufei's approach first [5733].
Tightening the guidance so CHANGELOG only covers changes worth calling out in release notes should cut a lot of the contention. That matches how Dimitri described the original intent. If we still collide often after that, I'm fine moving to Alex's changelog.d idea as the next step. Thanks Vignesh [5733] https://github.com/apache/polaris/pull/5733 On Thu, 8 Oct 2026 at 00:35, Dmitri Bourlatchkov <[email protected]> wrote: > Hi Yufei, > > Thanks for raising PR [5733]. I think it makes sense. Let's see how it > works out. > > [5733] https://github.com/apache/polaris/pull/5733 > > Cheers, > Dmitri. > > On Wed, Oct 7, 2026 at 2:31 PM Yufei Gu <[email protected]> wrote: > > > Dmitri’s clarification helps: we don’t need an entry for every PR, > > only changes worth calling out to users. I made the same point in my > > previous email. I hope this will significantly reduce merge conflicts. > > We could give it a try, and if conflicts are still there, we can adopt > > Alex ’s changelog.d proposal. WDYT? > > > > Yufei > > > > Yufei > > > > > > On Wed, Oct 7, 2026 at 7:04 AM Jean-Baptiste Onofré <[email protected]> > > wrote: > > > > > > Hi, > > > > > > I am fine with whichever approach the team decides. > > > > > > However, I personally am not convinced that maintaining a CHANGELOG is > > > necessary. In my view, the maintenance effort outweighs the actual > value > > it > > > provides. > > > Just my two cents. > > > > > > Regards, > > > JB > > > > > > > > > On Wed, Oct 7, 2026 at 3:45 PM Dmitri Bourlatchkov <[email protected]> > > wrote: > > > > > > > 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 > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
