Tag releases from CI, and document the flow

.github/workflows/build-main.yml

@@ -38,6 +38,8 @@ jobs:
     if: "contains(github.event.head_commit.message, 'Bump version')"
     needs: [lint-and-test]
     runs-on: ubuntu-latest
+    permissions:
+      contents: write  # needed to create the release tag
 
     steps:
     - uses: actions/checkout@v1
@@ -58,3 +60,26 @@ jobs:
         user: __token__
         password: ${{ secrets.PYPI_API_TOKEN }}
         repository_url: https://upload.pypi.org/legacy/
+    # bump2version tags the commit it creates, but a bump that arrives through a
+    # PR is squashed or rebased, so that tag would point at a commit which never
+    # reaches main -- v3.0.0 dangles that way and v3.1.0 was never tagged at all.
+    # Tag here instead, on the commit that actually published.
+    - name: Read the published version
+      id: version
+      run: |
+        version=$(grep -Po '(?<=^__version__ = ")[^"]+' inorbit_edge/__init__.py)
+        echo "value=$version" >> "$GITHUB_OUTPUT"
+    - name: Tag the release
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        VERSION: ${{ steps.version.outputs.value }}
+      run: |
+        if gh release view "v$VERSION" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+          echo "v$VERSION is already released; nothing to tag."
+          exit 0
+        fi
+        gh release create "v$VERSION" \
+          --repo "$GITHUB_REPOSITORY" \
+          --target "$GITHUB_SHA" \
+          --title "v$VERSION" \
+          --generate-notes

CONTRIBUTING.md

@@ -64,12 +64,29 @@ virtualenv venv
 pip install -e .[dev]
 ```
 
-Then run `bump2version` and choose the part of the version to be bumped, and don't forget to push changes and tags:
+Then run `bump2version` on a branch and choose the part of the version to be
+bumped. Pass `--no-tag`: CI tags the release itself, on the commit that actually
+publishes (see below).
 
 ```bash
-bump2version patch # possible: major / minor / patch
-git push
-git push --tags
+git checkout -b bump-version-x.y.z
+bump2version --no-tag patch # possible: major / minor / patch
+git push -u origin bump-version-x.y.z
 ```
 
-This will release a new package version on Git + GitHub and publish to PyPI.
+Open a pull request for it and **keep `Bump version` in the merge commit
+message**: the publish job triggers on
+`contains(github.event.head_commit.message, 'Bump version')`, and a squash merge
+takes the PR title, so leave the title as `bump2version` wrote it (`Bump version:
+x.y.z → a.b.c`).
+
+Merging publishes the package to PyPI, then creates the `vA.B.C` tag and a
+GitHub release from the published version.
+
+Why `--no-tag`: `bump2version` tags the commit it creates, which is only correct
+when the bump goes straight to `main`. Merge commits are disabled on this repo,
+so a bump arriving through a PR is squashed or rebased into a *different* commit
+and that tag would point at something never reachable from `main` — which is how
+`v3.0.0` came to dangle and `v3.1.0` was never tagged at all. Bumping directly on
+`main` still works if you prefer it (`bump2version patch`, then `git push && git
+push --tags`); the CI step skips tagging when the release already exists.