From ed35edd1fb466236a4e9073d6b36a51d4ff63765 Mon Sep 17 00:00:00 2001
From: Leandro Pineda <leandro@inorbit.ai>
Date: Wed, 29 Jul 2026 21:47:05 -0300
Subject: [PATCH 1/2] Tag releases from CI instead of by hand

bump2version tags the commit it creates, which works when a release is
bumped directly on main -- CONTRIBUTING's flow -- but not when the bump
arrives as a PR: squash and rebase both produce a different commit, so the
tag points at something that never reaches main. v3.0.0 dangles off a
discarded branch commit for that reason, and v3.1.0 was never tagged at
all, leaving setup.py's download_url for it broken.

The publish job now creates the tag and a GitHub release from the version
it just published, after PyPI succeeds, and skips if the release already
exists so a re-run is harmless.
---
 .github/workflows/build-main.yml | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/.github/workflows/build-main.yml b/.github/workflows/build-main.yml
index 6eb06aa..50f541a 100644
--- a/.github/workflows/build-main.yml
+++ b/.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

From ef62d68c7a5e2aed378945583a31a0dae2776e09 Mon Sep 17 00:00:00 2001
From: Leandro Pineda <leandro@inorbit.ai>
Date: Wed, 29 Jul 2026 21:48:02 -0300
Subject: [PATCH 2/2] Document the CI-tagged release flow

CONTRIBUTING told maintainers to bump on main and push tags, which no
longer matches how releases actually happen (a bump PR) and produced the
dangling v3.0.0 tag and the missing v3.1.0 one. Describes the branch + PR
flow with --no-tag, notes that the merge commit message has to keep 'Bump
version' for the publish job to fire, and keeps the bump-on-main variant
for anyone who prefers it.
---
 CONTRIBUTING.md | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9289470..40435bc 100644
--- a/CONTRIBUTING.md
+++ b/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.