Select a tool for automating release notes

[astrojuanlu]

Description

Our release notes (in Kedro and plugins) are all dumped to the same RELEASE.md. There are several problems with this:

• Contributors get confused https://github.com/kedro-org/kedro-plugins/pull/580/files#r1521259734
• Merge conflicts arise that need manual resolution
• Mistakes happen Remove duplicate sections from the release notes #3661

It would be nice if we could find an easier way of authoring the release notes. For example: https://scriv.readthedocs.io/ (that's what Vizro uses)

Spike: investigate scriv and towncrier and pick one of the two. Update contribution flow where needed.

[antonymilne]

Just came across this at random and thought I'd chip in. @maxschulz-COL might also have some thoughts on the matter.

Scriv is very straightforward and generally works great for us on vizro. We also have a check that prevents people from merging a PR without a changelog file (which could be empty if you don't want to add something to the changelog). This removes the need for a "I have added something to the changelog" checkbox in PRs or for reviews needing to remind authors to add something to the changelog. It does also add a small overhead since all PRs need to add a changelog file which adds a little friction to e.g. making quick edits to the docs from Github UI. So it may or may not be a good idea to implement on kedro - it's a question of whether having the PR checkbox vs. the CI check is on balance better. I've toyed with the idea of adding some kind of way to skip this CI check through a PR comment or similar (like https://github.com/pydantic/hooky?tab=readme-ov-file#change-file-checks) but didn't get around to doing anything about it.

In hindsight I wonder whether towncrier would be more suitable for us than scriv because scriv is very simple and basic. Towncrier looks more powerful e.g. it would be able to add the PR number to changelog messages automatically, which we have to do manually with scriv.

[maxschulz-COL]

Hey - just thought I'd answer for posterity :)

We chose scriv upon @astrojuanlu recommendation - and I agree with A that it serves its purpose quite well.

Back when deciding I glanced over the alternatives, and it seems the most lightweight tool out there.

Super interesting regarding alternatives, I remember that this bit from the scriv docs resonated with me regarding towncrier, and why maybe pass it (for now)

• towncrier: built for Twisted, with some unusual specifics: fragment type is the file extension, issue numbers in the file name. Only .rst files.

I think the rst point is outdated, .md files seem possible now!

Regarding the PR number, this would be quite a powerful reason to change, but I think it is not as simple as doing nothing, as (if I understand correctly) the user still has to type the number upon creation. However, the link is then automatically formatted and added, which is quite nice!

So maybe we should change at some point in the future, but I think the advantages are somewhat marginal for now.

[antonymilne]

Ah yes, you are right that the issue number doesn't get added automatically but would be formatted correctly automatically. Towncrier has better support for monorepo and also pre-commit hooks which are maybe useful for us on vizro. Generally it does look more powerful than scriv.

But yes, I don't have a big problem with scriv so agree that on vizro the possible advantages of towncrier are not especially worth doing a migration for any time soon. If you're thinking about it fresh on kedro though then towncrier definitely looks worth considering.

[astrojuanlu]

A significant amount of time and discussion was spent deciding in which section of the release notes to include each change kedro-org/kedro-viz#1919