Improve and document the release process

[simonevadi]

The release process is not documented. As far as I understand, this is the workflow at the moment:

1. Prepare the code you want released and merge it into main.
2. Create and push a Git tag in the form vX.Y.Z.
3. GitHub Actions builds the wheel with cibuildwheel.
4. The workflow uploads the built wheel to PyPI automatically.

What I think is missing here are two things: the develop branch, where to push all the work before the release and run the tests, and a changelog. I normally have a slightly different release workflow:

1. Merge feature work into develop.
2. Collect release notes in CHANGELOG.md under ## [Unreleased].
3. Run bash tools/release.sh on develop.
4. The script bumps the version, moves changelog notes into a dated release section, creates a release commit and tag, pushes both, opens a GitHub release, and creates a PR from develop to main.
5. main is updated only through that promotion PR.

But I like the automatic release from git that you set up, so I would propose a hybrid workflow:

• Make develop the place where release notes are prepared and the version is bumped.
• Keep the automatic CI build and PyPI publish from your workflow.
• Make the release script responsible only for:
  • moving changelog entries,
  • bumping the version,
  • creating the tag,
  • opening the PR to main

[simonevadi]

I implemented the proposed workflow in https://github.com/hz-b/rayx-python/tree/split/release-changelog

• the github workflow builds wheels on PRs and branch pushes, but only publishes to PyPI when a version tag like vX.Y.Z is pushed.
• The release.sh:
  1. Ensures the release is performed from the develop branch with a clean working tree.
  2. Guides the user in selecting the next semantic version.
  3. Updates CHANGELOG.md by promoting the Unreleased section to a dated release.
  4. Creates a release commit.
  5. Creates and pushes the Git tag.
  6. Pushes the release commit to develop.
  7. Opens a GitHub PR from develop to main.