replace changelog.md with support for github releases

[grst]

• more developer-friendly because no merge conflicts on changelog
• more user-friendly because nice integration in github UI
• organize with labels, see e.g. https://github.com/scverse/spatialdata/blob/main/.github/release.yml HT @LucaMarconato

[flying-sheep]

From our discussion: anndata/scanpy instead use towncrier together with some custom scripts¹, but we decided that ecosystem packages rarely end up needing that.

Footnotes

1. the advantages being 1. that we can use Sphinx links in that to get more interactive changelogs and 2. having a changelog that’s searchable ↩

[Czaki]

Few ideas that I observed:

1. Generate changelog based on commit list (git cliff
2. Generate changelog based on merged PR list (both tools are using separate file per version).
   • scikit-image
   • napari with multi repo changelog (see our scripts here https://github.com/NApari/napari-release-tools)
3. Generate changelog based on notes from special directory (mentioned above towncrier, used also by tox)

In general, having a changelog as a file is really nice in the context of documentation. Also simplify contribution with bug fixes.

In napari we have used such a changelog to provide also highlights (what are the most important changes). I agree that contributing to Changelog.md is a bad idea. But running some script by release manager to generate file, as last steep before release is a good idea.

The release manage should already have the repository copied on his machine to validate if everything is working.

[grst]

Hi @Czaki ,

thanks for your comment. Note that we don't want to abolish changelogs, we just want to replace it with a changelog automatically generated by GitHub. This is basically equivalent to

Generate changelog based on merged PR list

except that it doesn't require any custom tooling. The changelog would then be git Github release page, e.g. spatialdata. This can be linked from the documentation. If you want to show highlights, it is easy to manually edit the text and adjust it.

But running some script by release manager to generate file, as last steep before release is a good idea.

The release manage should already have the repository copied on his machine to validate if everything is working.

The release workflow we are proposing in this template doesn't require a release manager or a local machine. By using the PyPI "trusted publishing" workflow, it is as simple as create a release on GitHub. Of course one of your three options above could also be achieved with a custom github action, but I think the GitHub releases provide a decent default with no maintenance cost.

[Czaki]

thanks for your comment. Note that we don't want to abolish changelogs, we just want to replace it with a changelog automatically generated by GitHub. This is basically equivalent to

It is not equivalent. In such a situation, changelog is strongly connected to a single propertiary platform, is not easy searchable, lives outside the documentation.

If you want to show highlights, it is easy to manually edit the text and adjust it.

It could be done only by a person with write/admin access to the repository. With the file, any person could contribute suggestions for changes.

The release workflow we are proposing in this template doesn't require a release manager or a local machine

I still do not found a way to create tag without a copy of the repository on my local machine (with exception to custom callable workflow, that will have dangerous permission).

Also, without a release manager, who will be responsible to checking if code is in good quality to release?

[grst]

It is not equivalent. In such a situation, changelog is strongly connected to a single propertiary platform, is not easy searchable, lives outside the documentation.

I agree with the proprietary platform, but we (i.e. scverse) and this template are heavily bought into GitHub anyway (github actions, github apps, issue tracker etc.)

It could be done only by a person with write/admin access to the repository. With the file, any person could contribute suggestions for changes.

That's fair

I still do not found a way to create tag without a copy of the repository on my local machine (with exception to custom callable workflow, that will have dangerous permission).

Creating a release on GitHub does create a tag at the same time

Also, without a release manager, who will be responsible to checking if code is in good quality to release?

IMO the main branch should always be of sufficient quality to make a release.

I'm also not saying it's the perfect solution for everyone. But I do believe it's a reasonable default for most projects, especially for ecosystem packages that might not be maintained by highly experienced developers.

[flying-sheep]

One thing to go into is also conventional commits, especially when coupled with commitizen.

Maybe not for the template, as it’s pretty opinionated, but it would allow to get completely automated releases (and setting a label is also easy enough)

[grst]

IMO the solution here should be:

• use github releases as default (easy to use + appropriate for most smaller projects)
• show alternatives in the docs, e.g. conventional commits, towncrier