Hi all,

The changelog.d PR has been merged:

https://github.com/apache/polaris/pull/5967

Many thanks to the reviewers! Let's hope that this improvement will
simplify opening and maintaining PRs against the Polaris codebase.

Thanks,
Alex

On Thu, Nov 12, 2026 at 10:31 AM vignesh a <[email protected]> wrote:
>
> Hi all,
>
> +1 on changelog.d. The narrower rule from #5733 [1] was a
> reasonable first step, but conflicts are still landing on
> Unreleased, so fragments look like the right next step.
> Waiting to merge #5967 [2] until 1.9.0 is cut, as Alex
> suggested, makes sense to me.
>
> Thanks,
> Vignesh
>
> [1] https://github.com/apache/polaris/pull/5733
> [2] https://github.com/apache/polaris/pull/5967
>
> On Fri, 6 Nov 2026 at 01:32, Dmitri Bourlatchkov via dev <
> [email protected]> wrote:
>
> > Hi Alex,
> >
> > Your suggestion sounds good to me.
> >
> > I agree that user friendliness is preferable. If it is not too hard to
> > process the new layout in the tool, let's go with that.
> >
> > Thanks,
> > Dmitri.
> >
> > On Thu, Nov 5, 2026 at 1:21 PM Alex Dutra via dev <[email protected]>
> > wrote:
> >
> > > Hi Dmitri, hi all,
> > >
> > > Thanks for the thorough reviews I've got so far!
> > >
> > > We are close to a PR approval. Having played with the feature myself,
> > > I wonder though if we couldn't simplify the layout you suggested, and
> > > make it just:
> > >
> > > changelog.d/<short-title>.md
> > >
> > > IOW:
> > >
> > > - drop the NN- requirement: I think most users will just use 99, and
> > > I'm not convinced that the order of items under a section really
> > > matters.
> > > - flat multi-section files: each fragment would be a "miniature
> > > changelog", i.e. a markdown file containing all the sections it
> > > contributes items for.
> > >
> > > My rationale is that I want fragments to be as cheap as possible to
> > > write, even if that means a more complex parsing logic on the Gradle
> > > side.
> > >
> > > WDYT?
> > >
> > > Thanks,
> > > Alex
> > >
> > >
> > > On Wed, Nov 4, 2026 at 6:30 PM Dmitri Bourlatchkov via dev
> > > <[email protected]> wrote:
> > > >
> > > > Hi Alex,
> > > >
> > > > Thanks for the PR! I left some comments in GH, but it looks great to me
> > > > overall.
> > > >
> > > > I'll defer to Robert for Gradle-specific fine points.
> > > >
> > > > Cheers,
> > > > Dmitri.
> > > >
> > > > On Tue, Nov 3, 2026 at 5:44 AM Alex Dutra via dev <
> > > [email protected]>
> > > > wrote:
> > > >
> > > > > Hi Dmitri, Ayush,
> > > > >
> > > > > I went ahead and implemented the changelog.d feature using your
> > design
> > > > > suggestions:
> > > > >
> > > > > https://github.com/apache/polaris/pull/5967
> > > > >
> > > > > PTAL.
> > > > >
> > > > > Thanks,
> > > > > Alex
> > > > >
> > > > > On Fri, Oct 30, 2026 at 12:27 AM Dmitri Bourlatchkov <
> > [email protected]
> > > >
> > > > > wrote:
> > > > > >
> > > > > > Hi Alex, Ayush,
> > > > > >
> > > > > > I agree that the pain is real.
> > > > > >
> > > > > > My preference is also with option 1 (changelog.d).
> > > > > >
> > > > > > Proactive suggestion for file name pattern:
> > > > > > changelog.d/<section>/NN-<short-title>.md
> > > > > >
> > > > > > The file should contain plain MD text suitable for inclusion in a
> > > list in
> > > > > > the generated changelog.
> > > > > >
> > > > > > NN is the relative priority. Collisions are allowed and get resolve
> > > by
> > > > > > <short-title>. Smaller numbers are listed higher in the final doc.
> > > > > >
> > > > > > Suggestion: use NNN=99 if priority is not critical.
> > > > > >
> > > > > > On release the included files are simply deleted from `main`.
> > > > > >
> > > > > > WDYT?
> > > > > >
> > > > > > Thanks,
> > > > > > Dmitri.
> > > > > >
> > > > > > On Thu, Oct 29, 2026 at 12:30 PM Ayush Saxena <[email protected]>
> > > > > wrote:
> > > > > >
> > > > > > > Thanks for restarting this thread, Alex.
> > > > > > >
> > > > > > > Regarding Option 2: I tested it, but it isn't working on my end.
> > > Even
> > > > > > > if it did, it would be difficult to enforce since it requires
> > > > > > > educating the team on the new process.
> > > > > > >
> > > > > > > Option 1 looks like the best approach to me, once we finalize the
> > > > > > > naming conventions and the release script.
> > > > > > >
> > > > > > > -Ayush
> > > > > > >
> > > > > > > On Thu, 29 Oct 2026 at 21:51, Alex Dutra <[email protected]>
> > > wrote:
> > > > > > > >
> > > > > > > > Hi all,
> > > > > > > >
> > > > > > > > I'm reviving this thread because the pain is real :-)
> > > > > > > >
> > > > > > > > Can we agree on _something_  that would get rid of constant
> > > > > conflicts?
> > > > > > > >
> > > > > > > > To summarize the options discussed thus far:
> > > > > > > >
> > > > > > > > 0. No curated changelog file at all
> > > > > > > > - Pros: the file and its conflicts go away. No author effort.
> > > > > > > > - Cons: The release notes are mostly a git log that few users
> > > read.
> > > > > > > > Non-breaking user-facing notes and upgrade caveats aren't
> > > captured.
> > > > > > > >
> > > > > > > > 1. changelog.d/ fragments (one small file per PR, merged into
> > > > > > > > CHANGELOG.md at release)
> > > > > > > > - Pros: no shared lines, so no conflicts. Entries can be fixed
> > > after
> > > > > > > > merge. Reviewers can comment line by line. Fragments carry over
> > > into
> > > > > > > > cherry-picks.
> > > > > > > > - Cons: filename scheme to settle (PR numbers aren't known
> > > upfront).
> > > > > > > > Needs a RAT exclusion. Needs a release script.
> > > > > > > >
> > > > > > > > 2. Keep CHANGELOG.md and resolve conflicts in the GitHub UI
> > > > > > > > - Pros: no process change. Resolving takes a few seconds and
> > > needs no
> > > > > > > > re-approval.
> > > > > > > > - Cons: CI re-runs on every merge commit. The friction stays.
> > > > > > > >
> > > > > > > > 3. Generate the release notes with AI at release time
> > > > > > > > - Pros: little author effort.
> > > > > > > > - Cons: it can silently omit breaking changes. Output isn't
> > > > > > > > reproducible for release votes. AI can't surface caveats that
> > > nobody
> > > > > > > > wrote down.
> > > > > > > >
> > > > > > > > 4. Changelog text in commit messages
> > > > > > > > - Pros: no extra files. Works with cherry-picks.
> > > > > > > > - Cons: CI can't enforce it. The merger can overwrite the
> > > author's
> > > > > > > > text. GitHub's default message pulls in unrelated text. Editing
> > > it
> > > > > > > > after a long review is heavy.
> > > > > > > >
> > > > > > > > 5. PR label plus a CHANGELOG comment, assembled at release
> > > > > > > > - Pros: no files in the repo.
> > > > > > > > - Cons: entries live in PR comments, so they're hard to review
> > or
> > > > > fix.
> > > > > > > > It depends on a release workflow that scrapes GitHub.
> > > > > > > >
> > > > > > > > What do you all prefer?
> > > > > > > >
> > > > > > > > Thanks,
> > > > > > > > Alex
> > > > > > > >
> > > > > > > > On Wed, Oct 7, 2026 at 10:53 PM vignesh a <
> > > [email protected]>
> > > > > > > wrote:
> > > > > > > > >
> > > > > > > > > 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
> > > > > > > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > > >
> > > > > > > > > > > > > > > >
> > > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > >
> > > > >
> > >
> >

Reply via email to