[jonathan-kosgei]

Summary

• Add a release job to .github/workflows/python-publish.yml that runs after the test matrix on every push to master, reads the version from setup.cfg and, when no tag of that name exists yet, creates the tag and the GitHub release (with generated notes) in one step.
• Make build-n-publish wait for that job and upload to PyPI when the tag was created in the same run; a tag pushed by hand still publishes as before.
• Add a maintainer-facing "Releasing" section to the README.

How it works

• release is guarded by github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch), needs test, runs with permissions: contents: write and in the release concurrency group without cancellation, so two merges in a row release one after the other.
• It reads the version with sed -nE 's/^version *= *([^[:space:]]+).*/\1/p' setup.cfg | head -1 (tags carry no v prefix, matching the existing tags) and checks git ls-remote --exit-code --tags origin "refs/tags/$TAG": exit 0 means the tag exists and the job reports that there is nothing to release (created=false); exit 2 means it is missing, so gh release create "$TAG" --target "$GITHUB_SHA" --title "$TAG" --generate-notes creates the tag and the release with the workflow's own GITHUB_TOKEN (created=true); any other exit code fails the job.
• A tag created with GITHUB_TOKEN does not start another workflow run, so publishing happens in the same run: build-n-publish now has needs: [test, release] and its "Publish to PyPI" step runs when needs.release.outputs.created == 'true' or, as before, when the run was started by a tag push (startsWith(github.ref, 'refs/tags')). The job itself still runs for every push (full test suite with the API key, then the build), and its condition tolerates the release job being skipped on tag pushes.
• Nothing else changes: the pull_request test matrix, the full-suite run on master, the publish steps and the secrets they use are as before. The version currently in setup.cfg (4.1.0) is already tagged, so merging this pull request releases nothing by itself.

Verification

• python3 -c 'import yaml,sys; [yaml.safe_load(open(f)) for f in sys.argv[1:]]' .github/workflows/*.yml passes.
• actionlint .github/workflows/*.yml (v1.7.12) reports nothing.
• The version command prints 4.1.0 for the checked-out setup.cfg.
• The test matrix runs on this pull request; the push-only release job can only be exercised by a merge.

🤖 Generated with Claude Code