Thanks for your feedback, Yufei. Let me clarify a bit the proposal On Fri, Aug 22, 2025 at 2:47 AM Yufei Gu <flyrain...@gmail.com> wrote:
> I'm not a big fan of it, as I'm not sure how we execute it effectively. > 1. How do we define "applicable" PR? > If we want to be exhaustive, indeed, we can come up with a list of changes that require a changelog update. My intent with the word "applicable" was more about saying that it is not mandatory, and it is up to contributors/reviewers to determine whether a changelog update is necessary. I.e. keep some flexibility, do not push a new strict constraint on all code changes yet. As we develop this new habit, I expect this list to evolve a couple of times. > 3. What should go to changelog for each individual PR when a feature is > splitted to multiple PRs? > I think the changelog should be updated when the feature becomes available to users. Before that, AFAICT, the code changes would be prep work (refactorings, new classes) but would not yield any visible change for the end user. > 2. What if they are reverted? > There are multiple facets to this question. Typically, if a change is self-contained vs if it is split over multiple PR, if a change is reverted after it has been released, and more. If the change has already been included in a release, then the entry in the changelog will be in the section dedicated to that release. It will not be in the "Unreleased" section anymore. So the `git revert` operation will need additional care in order not to modify the past. Although I wonder whether we would really revert a change in that situation, instead of deprecating it for removal... You can see that it is related to the API/SPI ongoing discussion. Now, if it has not been released yet, and the change has been split into multiple PRs, I think we should evaluate the need for a changelog update based on the end user perception. If the feature is not available to the end user anymore, then the revert should remove the entry from the changelog. > I'd suggest that if we really want it, we need a clear definition what > should go to changelog. For example > 1. spec changes > 2. interface changes: deprecation/removal > 3. configure changes: add a new config, remove a config, etc. My intent was not to challenge the current list of elements in the changelog. I think we should use what exists as much as possible, until we find the limits of the current state and want to evolve it. AFAICT, the changelog already contains sections for: * breaking changes (which includes removals) * deprecations * new features (which include any user-visible change, like configuration changes) * highlights (which can be used for even more important changes like spec changes) Am I missing something? -- Pierre
