Automate release on pyproject version bump

[jantman]

Switches the release model from "push a git tag" to "bump the version in pyproject.toml on main", matching the pattern used in our other modern repos (e.g. equipment-status-board).

How it works now

release.yml triggers on push to main and:

1. Reads the version from pyproject.toml.
2. Compares it to the latest GitHub release.
3. If higher, it: creates the git tag (bare version, e.g. 0.14.0 — no v prefix, matching existing tags), builds & pushes the Docker image to GHCR, publishes to PyPI, and creates a GitHub release with auto-generated notes plus docker-pull / PyPI pointers.
4. If unchanged, the workflow no-ops (every merge runs it, but only version bumps release).

No more manual tagging.

Notes

• Carries forward the lowercase-GHCR-repo fix from Lowercase GHCR image repository name in docker builds #159 and the SBOM / OCI labels. The image version label now comes from the detected version instead of github.ref_name (which would be main on a branch push).
• Keeps PyPI publishing via JRubics/poetry-publish; the CLAUDE_CODE_OAUTH_TOKEN and PYPI_TOKEN secrets are already present on the repo.
• Tags are pushed by the workflow but don't re-trigger it (it only listens to branch pushes, not tag pushes).

Docs

• docs/source/contributing.rst — rewrote the Release Process section.
• CLAUDE.md — added a Releasing section documenting the auto-release-on-version-bump flow and "do not tag manually."
• README.rst — no change (it has no release/tag content).

Effect on the pending 0.14.0 release

pyproject.toml is already at 0.14.0 and the latest release is 0.13.0. Merging this PR will itself trigger the new workflow and auto-release 0.14.0 — so this replaces the manual tag-and-release step we paused earlier.

🤖 Generated with Claude Code

[github-actions]

Coverage Report

File	Stmts	Miss	Branch	BrPart	Cover	Missing
src/dm_mac
__init__.py	73	0	6	0	100%
cli_utils.py	15	0	0	0	100%
neon_fob_adder.py	232	15	60	5	93%	79, 116–117, 124, 270, 333–334, 341, 364–367, 454–456
neongetter.py	211	1	54	3	99%	309
slack_handler.py	220	0	56	0	100%
utils.py	25	0	4	0	100%
src/dm_mac/models
__init__.py	0	0	0	0	100%
api_schemas.py	34	0	0	0	100%
machine.py	592	16	200	16	97%	615, 695, 987–989, 1101–1110, 1168
users.py	103	0	32	0	100%
src/dm_mac/views
__init__.py	0	0	0	0	100%
api.py	32	0	0	0	100%
machine.py	103	0	12	0	100%
prometheus.py	132	0	12	1	100%
TOTAL	1772	32	436	25	98%

Tests	Skipped	Failures	Errors	Time
312	0 💤	0 ❌	0 🔥	24.562s ⏱️

[claude]

Two related issues in this version comparison block:

1. Shell injection via variable interpolation

$CURRENT_VERSION and $LATEST_VERSION are interpolated directly into a python3 -c source string, landing inside single-quoted Python string literals. The version regex [^"]+ on line 33 permits any character except " — including a single quote, which is sufficient to break out of the Python literal. In a runner holding contents: write, packages: write, and PYPI_TOKEN this is a code-execution sink. (You already avoided this exact pattern later with the comment # Build release body in a file to avoid shell escaping issues — the same concern applies here.)

Context: release.yml L43–49

2. int() crash on non-numeric version components

tuple(int(x) for x in ...) has no error handling. A pre-release version like 0.15.0b1 or 0.15.0.dev0 (produced by poetry version prerelease) splits to ['0', '15', '0b1'] — int('0b1') raises ValueError and the workflow fails.

Context: release.yml L44–48

Suggested fix: pass versions through the environment (data, not source code) and add error handling:

# Replace lines 44–48 with:
SHOULD=$(CURRENT_VER="$CURRENT_VERSION" LATEST_VER="$LATEST_VERSION" python3 -c "
import os, sys
def to_tuple(v):
    try:
        return tuple(int(x) for x in v.split('.'))
    except ValueError:
        print(f'non-numeric version: {v}', file=sys.stderr); sys.exit(1)
print('true' if to_tuple(os.environ['CURRENT_VER']) > to_tuple(os.environ['LATEST_VER']) else 'false')
")

[claude]

Non-atomic release: PyPI publishes before the GitHub release (the idempotency gate)

should_release is computed by checking whether a GitHub release exists for the current version (line 37). This PyPI publish step (L76–80) runs four steps before "Create GitHub Release" (L87–115). If the job fails or is cancelled after PyPI publishes but before the GitHub release step completes, the next rerun computes should_release=true again (no GitHub release found) and then fails permanently at this step — PyPI rejects re-uploading an already-published version with HTTP 400 ("File already exists"). The release steps are non-atomic and the idempotency gate is written last.

Context: release.yml L75–115

Suggested fixes (pick one):

• Add skip_existing: true to JRubics/poetry-publish so reruns skip an already-published version rather than erroring, making this step idempotent.
• Reorder steps so the GitHub release is created before the PyPI publish, so the gating condition becomes true before the irreversible action.