Proposal: Smarter CHANGELOG generation with `git-cliff` #2337

[jeertmans]

As discussed in #2337, I think the git-cliff tool might be a good way to easily deal with CHANGELOG management.

To support my point, I created this PR with some config file that generates CHANGELOG files with a body similar to the current CHANGELOG file.

I also made some dummy commits and updated the CHANGELOG with:

git cliff --unreleased --tag HEAD --prepend CHANGELOG.md v0.16.5...HEAD

As explained below, the v0.16.5...HEAD argument does not seem to have any effect on selected tags, but I doubt that can't be solved :-)

Pros:

• Undesired commits are ignored
• PR / Issues are automatically linked when #number is present in a commit message
• Tags comparison links are automatically generated
  • Note: didn't even notice that GitHub automatically linked versions comparisons (but it is limited to github.com I guess)
• Highly customizable config file

Cons:

• Requires to use conventional commits on the main branch (at least those you want to list in the CHANGELOG)
• Requires to add PR #number to commit message (normally, it's automatically proposed when merging)
• Merging PR should preferably now squash commits into a single commit

To fix:

• [ ] Make sure that previous parts of the CHANGELOG stay unchanged
  • This is possible with --prepend argument, but more test have to be performed
• [ ] Only parse commits after a given tags (i.e., after this PR is approved, if it is the case) with commits range
  • This should be possible using <RANGE> arguments, like so v0.16.5...HEAD, but does not seem to work (see example in files changed)

Further ideas:

• Use GitHub actions to generate changelog

[CLOVIS-AI]

Merging PR should preferably now squash commits into a single commit.

I'm not a PyO3 maintainer, so the decision is ultimately up to them, but as a user that is not something I'd like. I regularly use the history to understand how/why a change was made, and removing this information seems like a bad idea to me.

[adamreichold]

Merging PR should preferably now squash commits into a single commit.

I'm not a PyO3 maintainer, so the decision is ultimately up to them, but as a user that is not something I'd like. I regularly use the history to understand how/why a change was made, and removing this information seems like a bad idea to me.

I would like to second that. Especially if the way commits are cut is changed to accommodate a tool and not a human writing or usually more importantly reading the code.

[jeertmans]

Merging PR should preferably now squash commits into a single commit.

I'm not a PyO3 maintainer, so the decision is ultimately up to them, but as a user that is not something I'd like. I regularly use the history to understand how/why a change was made, and removing this information seems like a bad idea to me.

Hi! I am totally aware of those drawbacks and that this solution isn’t perfect. The pro of using squash was to not force external contributors to write commits in a specific way. And squash commits can still contain the messages from squashed commits.

[davidhewitt]

My own view: I like to keep a tidy git history for the PyO3 repository, and so I regularly make a judgement call whether to squash a PR or not based on factors like its size and how well delineated the commits made by the PR author are. 2000-line commits are unhelpful if git besect points to them for breakages for sure. On the other hand, tiny tweaks to a PR to fix various CI nits are also not of much value long term.

I'm curious to play around with this approach (and others) for generating the changelog if it can help us avoid merge conflicts. Personally I'm waiting until 0.17.0 is done so we can start with a cleaner slate.

Requires to add PR #number to commit message (normally, it's automatically proposed when merging)

The downside of this is that typically the PR number is only known after committing and pushing :)

[davidhewitt]

Thank you for this suggestion! After some time thinking about it and trying out this as well as towncrier, I felt I preferred #2607 so will close this one.