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