Re: [DISCUSS] On-going CHANGELOG with breaking changes

[Dmitri Bourlatchkov <di...@apache.org>]

Here's a PR to implement what was discussed in this thread. Please review:

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

Cheers,
Dmitri.

On Mon, May 19, 2025 at 5:54 AM Robert Stupp <sn...@snazy.de> wrote:

> +1 on having a CHANGELOG. That's been proven to be very useful.
>
> Change-log and release-notes (as a list of all commits) are orthogonal
> IMO. The former, as Dmitri mentioned, accumulates important changes in
> categories (highlights, breaking changes, new features, fixes). The
> latter is a "list of everything".
>
> The change-log is populated manually in a PR. It contains information
> from the authors to the users. Release-notes is a generated list of all
> commits.
>
>
> On 16.05.25 18:01, Jean-Baptiste Onofré wrote:
> > Yes but I mean that the content is already in the release notes.
> >
> > So let’s do it :)
> >
> > Regards
> > JB
> >
> > Le ven. 16 mai 2025 à 16:47, Dmitri Bourlatchkov <di...@apache.org> a
> > écrit :
> >
> >> I'm proposing CHANGELOG not as a replacement for Release Notes, but as
> >> a method for accumulating important notices as PRs are merged between
> >> releases.
> >>
> >> CHANGELOG could be used as input into Release Notes (or standalone).
> >>
> >> Cheers,
> >> Dmitri.
> >>
> >> On Fri, May 16, 2025 at 9:42 AM Jean-Baptiste Onofré <jb...@nanthrax.net>
> >> wrote:
> >>
> >>> The release manager can organize the changelog but he can’t populate
> it.
> >>> Only the authors of the change can (with the reviewer).
> >>>
> >>> Generally speaking, I think we can be helped by a PR label that can
> >>> pre-populate the changelog. But changelog or label has to be set by the
> >>> original author.
> >>>
> >>> Honestly, not sure a changelog (compared to release notes) would be
> super
> >>> helpful but we can give it a try.
> >>>
> >>> Regards
> >>> JB
> >>>
> >>> Le ven. 16 mai 2025 à 08:09, Yufei Gu <fl...@gmail.com> a écrit :
> >>>
> >>>> It does seem to introduce quite a bit of manual overhead. I’m
> >> personally
> >>>> not a big fan of that, but I’m open to trying it out. That said, I
> >>> believe
> >>>> the release manager should have the ability to organize the changelog
> >> at
> >>>> release time, since it’s quite difficult to maintain consistency from
> >> the
> >>>> perspective of individual PRs. For example, contributors might add
> >>>> something, then revise or remove it later. If the changelog entries
> are
> >>>> immutable, the history could become messy and confusing. Dmitri
> >> mentioned
> >>>> that changelog could be updated by PRs, which seems a reasonable
> fixing
> >>>> resort to me.
> >>>>
> >>>> Yufei
> >>>>
> >>>>
> >>>> On Thu, May 15, 2025 at 7:27 PM Jean-Baptiste Onofré <jb@nanthrax.net
> >
> >>>> wrote:
> >>>>
> >>>>> Hi Dimitri
> >>>>>
> >>>>> It's a good idea.
> >>>>>
> >>>>> I think each committer should be responsible to update the CHANGELOG
> >>>>> if appropriate, and reviewer should point it out if needed.
> >>>>>
> >>>>> It's the same as documentation, license update and header (when code
> >>>>> is copied from another project), etc.
> >>>>>
> >>>>> Regards
> >>>>> JB
> >>>>>
> >>>>> On Thu, May 15, 2025 at 9:10 PM Dmitri Bourlatchkov <
> >> dimas@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
>
> --
> Robert Stupp
> @snazy
>
>

Re: [DISCUSS] On-going CHANGELOG with breaking changes

[Dmitri Bourlatchkov <di...@apache.org>]

Hi All,

I merged PR 1952.

For new PRs please add CHANGELOG entries for changes that need to be made
(more) visible to users.

Thanks,
Dmitri.

On Thu, Jun 26, 2025 at 4:02 PM Dmitri Bourlatchkov <di...@apache.org>
wrote:

> Here's a PR to implement what was discussed in this thread. Please review:
>
> https://github.com/apache/polaris/pull/1952
>
> Cheers,
> Dmitri.
>
> On Mon, May 19, 2025 at 5:54 AM Robert Stupp <sn...@snazy.de> wrote:
>
>> +1 on having a CHANGELOG. That's been proven to be very useful.
>>
>> Change-log and release-notes (as a list of all commits) are orthogonal
>> IMO. The former, as Dmitri mentioned, accumulates important changes in
>> categories (highlights, breaking changes, new features, fixes). The
>> latter is a "list of everything".
>>
>> The change-log is populated manually in a PR. It contains information
>> from the authors to the users. Release-notes is a generated list of all
>> commits.
>>
>>
>> On 16.05.25 18:01, Jean-Baptiste Onofré wrote:
>> > Yes but I mean that the content is already in the release notes.
>> >
>> > So let’s do it :)
>> >
>> > Regards
>> > JB
>> >
>> > Le ven. 16 mai 2025 à 16:47, Dmitri Bourlatchkov <di...@apache.org> a
>> > écrit :
>> >
>> >> I'm proposing CHANGELOG not as a replacement for Release Notes, but as
>> >> a method for accumulating important notices as PRs are merged between
>> >> releases.
>> >>
>> >> CHANGELOG could be used as input into Release Notes (or standalone).
>> >>
>> >> Cheers,
>> >> Dmitri.
>> >>
>> >> On Fri, May 16, 2025 at 9:42 AM Jean-Baptiste Onofré <jb...@nanthrax.net>
>> >> wrote:
>> >>
>> >>> The release manager can organize the changelog but he can’t populate
>> it.
>> >>> Only the authors of the change can (with the reviewer).
>> >>>
>> >>> Generally speaking, I think we can be helped by a PR label that can
>> >>> pre-populate the changelog. But changelog or label has to be set by
>> the
>> >>> original author.
>> >>>
>> >>> Honestly, not sure a changelog (compared to release notes) would be
>> super
>> >>> helpful but we can give it a try.
>> >>>
>> >>> Regards
>> >>> JB
>> >>>
>> >>> Le ven. 16 mai 2025 à 08:09, Yufei Gu <fl...@gmail.com> a écrit
>> :
>> >>>
>> >>>> It does seem to introduce quite a bit of manual overhead. I’m
>> >> personally
>> >>>> not a big fan of that, but I’m open to trying it out. That said, I
>> >>> believe
>> >>>> the release manager should have the ability to organize the changelog
>> >> at
>> >>>> release time, since it’s quite difficult to maintain consistency from
>> >> the
>> >>>> perspective of individual PRs. For example, contributors might add
>> >>>> something, then revise or remove it later. If the changelog entries
>> are
>> >>>> immutable, the history could become messy and confusing. Dmitri
>> >> mentioned
>> >>>> that changelog could be updated by PRs, which seems a reasonable
>> fixing
>> >>>> resort to me.
>> >>>>
>> >>>> Yufei
>> >>>>
>> >>>>
>> >>>> On Thu, May 15, 2025 at 7:27 PM Jean-Baptiste Onofré <
>> jb@nanthrax.net>
>> >>>> wrote:
>> >>>>
>> >>>>> Hi Dimitri
>> >>>>>
>> >>>>> It's a good idea.
>> >>>>>
>> >>>>> I think each committer should be responsible to update the CHANGELOG
>> >>>>> if appropriate, and reviewer should point it out if needed.
>> >>>>>
>> >>>>> It's the same as documentation, license update and header (when code
>> >>>>> is copied from another project), etc.
>> >>>>>
>> >>>>> Regards
>> >>>>> JB
>> >>>>>
>> >>>>> On Thu, May 15, 2025 at 9:10 PM Dmitri Bourlatchkov <
>> >> dimas@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
>>
>> --
>> Robert Stupp
>> @snazy
>>
>>