Update release process post 0.10.0

[LourensVeen]

This updates the release documentation with the things I ran into when releasing 0.10.0.

One issue we still have is that I have to temporarily disable branch protection to merge the release branch back into develop, and another is that we can't use setuptools-scm because develop doesn't have the version tags in its past. I'm going to think about whether we can tweak the release process to fix that, and maybe to automate it a bit more, but that's for another time.

[maarten-ic]

One issue we still have is that I have to temporarily disable branch protection to merge the release branch back into develop

Right, the branch protection rules require that there's an approved Pull Request before allowing merges.

and another is that we can't use setuptools-scm because develop doesn't have the version tags in its past.

I'm not sure if setuptools-scm will be very easy for muscle3, since the VERSION also needs to be included in the C++ (and Fortran) libraries.

I'm going to think about whether we can tweak the release process to fix that, and maybe to automate it a bit more, but that's for another time.

I'm happy to discuss this with you some time

[maarten-ic]

Suggested change

	version should be set to ``x.y.z-dev0``, where ``x.y.z`` is the next expected
	version should be set to ``x.y.z.dev0``, where ``x.y.z`` is the next expected

which is the normalized PEP-440 notation (https://peps.python.org/pep-0440/#development-release-separators)

[LourensVeen]

Ah, drat. I actually vaguely remember there being some kind of issue with PEP440 and semantic versioning disagreeing on what was and wasn't allowed. But PEP440 compliance is probably more important, as that's what the tooling uses.

[LourensVeen]

About the VERSION file: in AMUSE I'm using hatchling with versioningit instead of setuptools and setuptools-scm, and versioningit lets you write plugins. I made one of those that gets the version from git if we're in a repo, and from a central VERSION file if we're in a tarball. The tarballs you download from GitHub are made with git archive, and that has a hook that lets you substitute the version into a file. Pretty neat altogether.

We could maybe do something similar here, but we'd need two implementations, one for the Python side maybe as a setuptools-scm plugin if it supports that, and one in the Makefile that does the same but puts the result into the C++ header. Well, not the highest-priority issue I guess 😄.

[maarten-ic]

About the VERSION file: in AMUSE I'm using hatchling with versioningit instead of setuptools and setuptools-scm, and versioningit lets you write plugins. I made one of those that gets the version from git if we're in a repo, and from a central VERSION file if we're in a tarball. The tarballs you download from GitHub are made with git archive, and that has a hook that lets you substitute the version into a file. Pretty neat altogether.

We could maybe do something similar here, but we'd need two implementations, one for the Python side maybe as a setuptools-scm plugin if it supports that, and one in the Makefile that does the same but puts the result into the C++ header. Well, not the highest-priority issue I guess 😄.

setuptools-scm has support for .git_archival.txt, and you could run python -m setuptools_scm from the Makefile and put that as version in a C++ header as well. So definitely doable!

But then we'd still get the same issue with github and diverging main and develop branches, so the tags are not in the history of the develop branch. That could be fixed by changing the release process slightly to:

1. Create release branch
2. Merge release branch to main
3. Add tag to main and create github release, python packages, etc.
4. Merge main back to develop

Either way, not the highest priority now :)