[release automation] Changelog fragments management

[webknjaz]

Description / Summary

I noticed that currently CHANGELOG.md is being managed manually. I have recently figured out how to configure Towncrier to work with Markdown so I wanted to ask if you want a PR integrating that. I also have a few companion integration — a GitHub App for a check on PRs and a Sphinx extension for rendering the upcoming changes.

Value / benefit

This would reduce some of the maintenance burden connected to the release preparation. I could also improve some of the surrounding automation to reduce human error (the extended series contributions would take a bit more time, though).

Implementation details

No response

Tasks to complete

No response

[chrisjsewell]

Thanks for the offer @webknjaz! I would certainly be interested to see how it works.

I would note though, my opinion on the changelog is that, at least the initial section, should be easily digestible by "non-technical" users, i.e. more of an explanation of the changes rather than just a list of commits (which you can just go to GitHub to see). An exemplar of this IMO is https://code.visualstudio.com/updates/v1_62, where you have descriptive documentation at the start, then the PR list at the bottom. If Towncrier could allow for this kind of workflow (part manual, part auto-generated) that would be great

(Also FYI, within EBP repos I was initially just using https://github.com/executablebooks/github-activity, but moved away from this.)

[webknjaz]

I agree with that opinion and that is exactly why Towncrier and similar workflows are valuable. Each PR must include a changelog fragment file, these files are accumulated in a folder but when the release is needed, you'd run towncrier and they'd be removed and rendered into the normal changelog file. There are markers in such a changelog file and towncrier adds new release section below such a marker allowing you to have arbitrary text above it. You can include that changelog file in Sphinx as needed too.

I usually include a section with an explanation for the contributors on how it works. Here's what I added in setuptools, for example, https://setuptools.pypa.io/en/latest/development/developer-guide.html#making-a-pull-request. I also like to emphasize that the writing style for the changelog entries must be quite different from what one would expect from commit messages. Traditionally, commits should use the imperative mood while changelogs describe what's happened already since the last release, hence they need to be in the past tense most of the time (or using another way to convey the changed state). And the audiences for these types of content are different, commits are for developers/contributors, they may go into technical detail and motivation; changelogs are for the end-users, they need to describe the high-level impact of the user-facing changes, the UX side of the story.

Here's one of the projects where it's implemented: https://ansible-pylibssh.readthedocs.io/en/latest/changelog/.

By the way, here's a public resource that documents why dumping git log is bad: https://keepachangelog.com/en/1.1.0/#bad-practices.

P.S. Towncrier generates the changelog content based on a Jinja2 template which makes it very flexible and you can improve it anytime. Plus, once you generate changelog, you can edit the changelog file as you wish too.

[webknjaz]

@chrisjsewell I think this https://github.com/executablebooks/MyST-Parser/pull/469 should demonstrate how this works + show what parts are adjustable.