feat: introduce a release script for automated version bumping and tagging, update release documentation to reflect its usage, and ignore __pycache__.

Author: evopen

.gitignore

@@ -3,3 +3,4 @@ build/
 dist/
 benchmark
 *.ipc
+__pycache__

README.md

@@ -31,6 +31,14 @@ requests validate the package, and version tags build Linux and Windows wheels
 for CPython 3.12, 3.13, and 3.14. Tag builds publish the validated artifacts
 to PyPI via Trusted Publishing after a strict version check.
 
+For releases, use the helper script so the package version and tag stay in
+lockstep:
+
+```bash
+uv run python scripts/release.py X.Y.Z
+git push origin HEAD vX.Y.Z
+```
+
 ## Minimal Usage
 
 ```python

RELEASE.md

@@ -9,6 +9,20 @@ Production releases must satisfy all of the following:
 - `[project].version` in `pyproject.toml` is `X.Y.Z`
 - `X.Y.Z` is not already published on PyPI
 
+Do not bump `pyproject.toml` and create tags as separate manual steps. Use the
+release script so the version bump, commit, and tag come from the same commit:
+
+```bash
+uv run python scripts/release.py X.Y.Z
+git push origin HEAD vX.Y.Z
+```
+
+Or let the script push both:
+
+```bash
+uv run python scripts/release.py X.Y.Z --push
+```
+
 ## Local Validation
 
 1. Clean old artifacts.
@@ -42,17 +56,17 @@ Production releases must satisfy all of the following:
 
 ## GitHub Source Release
 
-1. Push commit to `main`.
-2. Create and push tag.
-   - `git tag vX.Y.Z`
-   - `git push origin vX.Y.Z`
+1. Run the release script from a clean working tree.
+   - `uv run python scripts/release.py X.Y.Z`
+2. Push the release commit and tag.
+   - `git push origin HEAD vX.Y.Z`
 3. Wait for the release workflow to finish and download the generated artifacts if needed.
 4. Create GitHub release from the tag and include changelog notes.
 
 ## PyPI Publish
 
 1. Configure a Trusted Publisher for the repository on PyPI.
-2. Bump `[project].version` in `pyproject.toml`.
-3. Push a matching version tag (`vX.Y.Z`).
+2. Run the release script so `pyproject.toml` and the tag are created together.
+3. Push the resulting commit and matching version tag (`vX.Y.Z`).
 4. Wait for the `Release Artifacts` workflow to finish.
 5. Verify the package page and an install from PyPI.

scripts/release.py

@@ -0,0 +1,134 @@
+"""Prepare a release by bumping version, committing, and tagging in one step."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+import tomllib
+
+
+VERSION_RE = re.compile(r"^\d+\.\d+\.\d+$")
+PYPROJECT_VERSION_RE = re.compile(r'(?m)^version = "([^"]+)"$')
+
+
+def fail(message: str) -> int:
+    print(f"ERROR: {message}", file=sys.stderr)
+    return 1
+
+
+def run(*args: str, capture: bool = False) -> str:
+    result = subprocess.run(
+        args,
+        check=False,
+        text=True,
+        capture_output=capture,
+    )
+    if result.returncode != 0:
+        if capture and result.stderr:
+            print(result.stderr, file=sys.stderr, end="")
+        raise SystemExit(result.returncode)
+    return result.stdout if capture else ""
+
+
+def parse_version(version: str) -> tuple[int, int, int]:
+    if not VERSION_RE.fullmatch(version):
+        raise SystemExit(fail(f"Invalid version '{version}'. Expected X.Y.Z."))
+    major, minor, patch = version.split(".")
+    return int(major), int(minor), int(patch)
+
+
+def read_project_version(pyproject: Path) -> str:
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    return data["project"]["version"]
+
+
+def ensure_clean_tree() -> None:
+    status = run("git", "status", "--short", capture=True).strip()
+    if status:
+        raise SystemExit(
+            fail("Git working tree is not clean. Commit or stash changes first.")
+        )
+
+
+def ensure_no_existing_tag(tag: str) -> None:
+    existing = run("git", "tag", "--list", tag, capture=True).strip()
+    if existing:
+        raise SystemExit(fail(f"Tag {tag} already exists locally."))
+
+
+def update_pyproject_version(pyproject: Path, target_version: str) -> None:
+    text = pyproject.read_text(encoding="utf-8")
+    matches = PYPROJECT_VERSION_RE.findall(text)
+    if len(matches) != 1:
+        raise SystemExit(
+            fail("Expected exactly one top-level version entry in pyproject.toml.")
+        )
+    updated = PYPROJECT_VERSION_RE.sub(f'version = "{target_version}"', text, count=1)
+    pyproject.write_text(updated, encoding="utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Bump pyproject version, commit it, and create a matching tag."
+    )
+    parser.add_argument("version", help="Target release version in X.Y.Z format.")
+    parser.add_argument(
+        "--push",
+        action="store_true",
+        help="Also push HEAD and the new tag to origin.",
+    )
+    args = parser.parse_args()
+
+    pyproject = Path("pyproject.toml")
+    target_version = args.version
+    target_tuple = parse_version(target_version)
+    current_version = read_project_version(pyproject)
+    current_tuple = parse_version(current_version)
+    tag = f"v{target_version}"
+
+    print(f"Current version: {current_version}")
+    print(f"Target version:  {target_version}")
+
+    if target_tuple <= current_tuple:
+        return fail(
+            "Target version must be greater than current version "
+            f"({target_version} <= {current_version})."
+        )
+
+    ensure_clean_tree()
+    ensure_no_existing_tag(tag)
+
+    update_pyproject_version(pyproject, target_version)
+    updated_version = read_project_version(pyproject)
+    if updated_version != target_version:
+        return fail(
+            "pyproject.toml update did not persist the expected version "
+            f"({updated_version} != {target_version})."
+        )
+
+    commit_message = f"chore(release): {target_version}"
+    tag_message = f"Release {target_version}"
+
+    run("git", "add", "pyproject.toml")
+    run("git", "commit", "-m", commit_message)
+    run("git", "tag", "-a", tag, "-m", tag_message)
+
+    print(f"Created commit: {commit_message}")
+    print(f"Created tag:    {tag}")
+
+    if args.push:
+        run("git", "push", "origin", "HEAD")
+        run("git", "push", "origin", tag)
+        print("Pushed commit and tag to origin.")
+    else:
+        print("Next step:")
+        print(f"  git push origin HEAD {tag}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())