ci: add PyPI publish workflow with OIDC trusted publishing

[ccf]

Summary

Set up a CI-driven release pipeline so future PyPI publishes happen on tag push instead of from a developer's laptop. Uses OIDC trusted publishing — no PyPI tokens stored as repo secrets.

.github/workflows/publish.yml (new)

Triggers on:

• Pushing a v*.*.* tag → builds, verifies the tag matches the pyproject version, runs twine check --strict, publishes to TestPyPI, then to PyPI
• Manual workflow_dispatch with target=testpypi|pypi for rehearsals

Both uploads run inside named GitHub Environments (testpypi and pypi), so prod releases can be gated behind reviewer approval.

PUBLISHING.md (rewritten)

• One-time setup: register trusted publishers on PyPI + TestPyPI, create the two GitHub environments, and do one token-based upload to claim the useprimer project name (PyPI requires the project to exist before trusted publishing works)
• Per-release flow becomes: bump version → branch → PR → tag → CI publishes

Test plan

• python -m build from current main produces useprimer-0.2.0 artifacts
• python -m twine check --strict dist/* PASSED on both wheel + sdist
• After merge: configure trusted publishers + environments, then do the one-time token upload to claim useprimer
• Then cut v0.2.1 (bump pyproject) → CI publishes end-to-end

🤖 Generated with Claude Code

---

Note

Medium Risk
Introduces an automated release pipeline that can publish artifacts to TestPyPI/PyPI; misconfiguration or incorrect tagging/versioning could result in failed or unintended releases.

Overview
Adds a new GitHub Actions workflow (.github/workflows/publish.yml) to build and publish the package on v*.*.* tags (and via manual dispatch), using OIDC trusted publishing instead of stored PyPI tokens. The workflow builds wheel/sdist, runs twine check --strict, verifies the tag version matches pyproject.toml, publishes to TestPyPI first, then to PyPI via separate GitHub Environments (testpypi/pypi) to support approval gating.

Rewrites PUBLISHING.md to document the new CI-driven release process, including one-time trusted publisher/environment setup, the initial token-based project claim, and the updated tag-based release and rehearsal steps.

^{Reviewed by Cursor Bugbot for commit 404396c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Manual PyPI dispatch is skipped
  • Added always() with explicit needs.build.result and needs.publish-testpypi.result checks to the publish-pypi job condition, allowing it to run when publish-testpypi is skipped during target=pypi dispatches.

Or push these changes by commenting:

@cursor push db33a8a5c8

Preview (db33a8a5c8)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -110,8 +110,13 @@
   publish-pypi:
     # Only tag pushes (or an explicit dispatch with target=pypi) reach prod.
     if: |
-      github.event_name == 'push' ||
-      (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+      always() &&
+      needs.build.result == 'success' &&
+      (needs.publish-testpypi.result == 'success' || needs.publish-testpypi.result == 'skipped') &&
+      (
+        github.event_name == 'push' ||
+        (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+      )
     needs: [build, publish-testpypi]
     runs-on: ubuntu-latest
     environment:

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit c9f2e14. Configure here.}