Who should own that consistency? Should the release manager normalize entries at cut time, or should each PR author follow a template up front?
I'd think it's the reviewers' (committers') duty to ensure consistency. PR authors are encouraged to add entries to CHANGELOG as needed, but reviewers should be mindful and suggest doing that if they perceive the PR changes Polaris behaviours in ways that are worth noting. Conversely, reviewers should reject noise from CHANGELOG. As for me, CHANGELOG entries are free-form text without a particular template. PR references are fine. They give details about how a change was implemented to interested readers and they do not cause too much clutter for uninterested readers, IMHO. I do not think release managers should handle that file manually during the release process. If there's a problem with the format or content, it would need a normal PR to fix. Cheers, Dmitri. On Thu, May 15, 2025 at 3:30 PM Yufei Gu <flyrain...@gmail.com> wrote: > Thanks for kicking this off, Dmitri—great idea! > > Looking at the current CHANGELOG, the entries range from PR-number > references to detailed feature write-ups and even small tweaks like “make > test less flaky.” To keep it useful, we probably need a consistent format. > > Who should own that consistency? Should the release manager normalize > entries at cut time, or should each PR author follow a template up front? > > > Yufei > > > On Thu, May 15, 2025 at 12:10 PM Dmitri Bourlatchkov <di...@apache.org> > wrote: > > > Hi All, > > > > As discussed in the community sync today, Polaris evolves quickly and > > breaking changes are a reality we have to live with :) > > > > However, I'd like to propose improving user and developer experience by > > keeping a change log with a section for breaking changes. > > > > We follow this practice in Nessie [1] with the help of the > > "jetbrains-changelog" build plugin to automate adding versioned sections > > [2] > > > > * PRs that have strong user-visible effects also update the appropriate > > section of the change log. > > * At release time, the "in progress" entries are moved to a version > > sub-section automatically. > > * I'd also propose additionally mentioning PRs with "breaking changes" on > > the dev ML list before merging. > > > > WDYT about introducing this workflow in Polaris? > > > > Thanks, > > Dmitri. > > > > [1] https://github.com/projectnessie/nessie/blob/main/CHANGELOG.md > > [2] https://github.com/projectnessie/nessie/pull/7243 > > >
