[jasperblues]

Fixes #158. The same design is in liberation-data/drivine4j#284 and liberation-data/drivine#332, so all three Drivine libraries release the same way.

Process (RELEASING.md):

1. A release PR bumps version in pyproject.toml.
2. Merging it is the release point. The maintainer tags the merge commit on main with vX.Y.Z and pushes the tag.
3. The tag push runs .github/workflows/release.yml.

release.yml

• Triggers.
  • push of a v* tag publishes.
  • workflow_dispatch, and a pull_request that touches release.yml, RELEASING.md, pyproject.toml or scripts/smoke_wheel.py, are dry runs that never publish. This PR's own run is the first dry run.
• check. On a tag push it fails with a clear message unless:
  • the tag is vX.Y.Z (with an optional -suffix);
  • it equals pyproject.toml's version;
  • the tagged commit is on main.
• gate. It runs ci.yml itself, which gains workflow_call: and is otherwise unchanged. It needs check, so a bad tag fails fast.
• build.
  • uv build (sdist, and a wheel built from it).
  • Fails a tag push if PyPI already has the version. A dry run only warns, and an unreachable PyPI warns and carries on.
  • twine check --strict.
  • scripts/smoke_wheel.py on Python 3.11 and 3.14. It installs the wheel into a clean venv, asserts the installed copy is the one imported, and runs python -m drivine.stubs on a throwaway project.
  • Uploads dist/ as an artifact.
• publish runs only on a tag, in the release environment. It publishes those exact files with pypa/gh-action-pypi-publish and trusted publishing, so no token is stored.
• github-release runs gh release create --generate-notes --verify-tag, and marks the release as a prerelease if the version has a -.
• Third-party actions are pinned to full SHAs. Permissions are contents: read, widened only per job: id-token: write on publish, contents: write on github-release.

Settings for the maintainer to add (no secrets):

1. A GitHub environment named release. Optionally give it required reviewers and a deployment tag rule v*.
2. A PyPI trusted publisher on the drivine project: owner liberation-data, repository drivine-python, workflow release.yml, environment release.

Review. Three passes; the third was clean.

• Pass 1 added the PyPI already-has-it check, the prerelease marking, and gate waiting on check.
• Pass 2 made that check survive a network error.

Checked locally without a publish: the build, twine check, the smoke test on 3.11 and 3.14, the tag check against a matching tag, a mismatched tag, a missing v and a commit off main, and bash -n on every step. The real publish and the trusted-publisher setup can only be tested on GitHub with a real tag.