use towncrier to generate CHANGELOG

[davidhewitt]

Uses towncrier to generate the CHANGELOG.

To see rendered CHANGELOG, see the netlify deploy preview at https://deploy-preview-2607--pyo3.netlify.app/main/changelog.html

[davidhewitt]

TODO:

• Update contributing guide
• Update PR templates
• Remove date from "Unreleased" header on rendered netlify build

[davidhewitt]

I'm quite happy with how this works! Anyone got any concerns before I merge this?

[messense]

No concerns, just a small question, otherwise LGTM!

[messense]

When doing a new release, do we need to update this version argument?

[adamreichold]

I think not for the Netlify build which will always contain the latest not-yet-released changes.

We will however have to run towncrier build when creating a release which will remove the news fragments from version control after having merged their contents into the changelog.

[davidhewitt]

Correct, the release step to update the real CHANGELOG is manual.

I'm going to take a moment in the next week or two to make some notes on how to do releases, even though I hope to continue to be doing them for the foreseeable future!

[adamreichold]

After reading the towncrier docs for a bit, this seems to mainly take care of writing the changelog, i.e. the formatting and parts of the editorial work, but will involve the same amount of additional work for developers making changes (meaning that in addition to the commit message, a news fragment which is basically the content part of a changelog item needs to be written).

To me this is certainly an improvement insofar it removes the Markdown busy work of keeping PyO3's high volume changelog in shape. But if this is automated at all, I would personally try to go for something that is based on the Git commit messages to reduce the number of steps involved in documenting changes. (Of course, it should not directly represent the commit log as the target audience is different, but it would be nice if it would derive the changelog item from the commit log using e.g. some mini language to use in the commit messages.)

[adamreichold]

I also really like that towncrier nicely integrates with the existing work instead of forcing us to redo the changelog or have a legacy and current one.

[aganders3]

This looks good to me, I'm glad it's working out!

[davidhewitt]

But if this is automated at all, I would personally try to go for something that is based on the Git commit messages to reduce the number of steps involved in documenting changes.

I went back and forth on this (see #2509), the advantage of encouraging cleaner commit history would be nice.

However the drawback of coupling to git commits is I think it forces contributors to learn how to add their release notes even earlier else be forced to squash / rebase.

Also, being able to fix up typos in release notes in follow up PRs is a huge plus for me.

So overall I'm leaning towards this approach, and it sounds like everyone is generally happy with it, so will click merge now! Can easily revert / revisit later given this is just internal tooling 🙂

[adamreichold]

However the drawback of coupling to git commits is I think it forces contributors to learn how to add their release notes even earlier else be forced to squash / rebase.

I agree that this is a significant drawback that I did not consider. I also very much agree that it is more useful to make thing easy for new contributors than to streamline things for the old hands.