Polish PyPI release automation

Author: ponythewhite

.github/workflows/release.yml

@@ -6,6 +6,10 @@ on:
       - "v*"
   workflow_dispatch:
 
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
 permissions:
   contents: write
   id-token: write
@@ -32,7 +36,7 @@ jobs:
         with:
           maturin-version: v1.13.1
           target: ${{ matrix.target }}
-          manylinux: "2_28"
+          manylinux: "2014"
           args: --release --locked --compatibility pypi --out dist --features openblas-static -i python${{ matrix.python-version }}
 
       - name: Upload wheel artifact
@@ -141,6 +145,16 @@ jobs:
           find artifacts -type f \( -name '*.whl' -o -name '*.tar.gz' \) -exec cp {} dist/ \;
           ls -lh dist
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Validate distribution metadata
+        run: |
+          python -m pip install --upgrade pip twine
+          python -m twine check --strict dist/*
+
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:

README.md

@@ -690,6 +690,25 @@ Relevant files:
 
 The release workflow builds wheels with `openblas-static` enabled so binary installs are as self-contained as practical.
 
+### Releasing to PyPI
+
+The PyPI project name is `pqk`.
+
+Once the one-time PyPI Trusted Publisher setup is done for:
+
+- owner: `BaseModelAI`
+- repository: `pkq`
+- workflow: `.github/workflows/release.yml`
+- environment: `pypi`
+
+the normal release path is:
+
+```bash
+python scripts/release.py 1.0.1 --commit --tag --push
+```
+
+That updates the version in the release metadata, creates the release commit, creates tag `v1.0.1`, and pushes both to `origin`. The tag push triggers the GitHub release workflow, which builds the wheels and publishes them to PyPI.
+
 ## Original project and related work
 
 ### Original implementation

pyproject.toml

@@ -9,7 +9,8 @@ description = "Modern Rust implementation of PQk-means for large-scale clusterin
 readme = "README.md"
 requires-python = ">=3.10"
 license = { file = "LICENSE" }
-authors = [{ name = "Codex" }]
+authors = [{ name = "Jacek Dąbrowski", email = "ponythewhite@gmail.com" }]
+maintainers = [{ name = "BaseModelAI" }]
 keywords = ["clustering", "product-quantization", "pqkmeans", "vector-search", "rust", "parquet"]
 classifiers = [
   "Development Status :: 5 - Production/Stable",
@@ -32,6 +33,12 @@ dependencies = [
   "pyarrow>=15.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/BaseModelAI/pkq"
+Repository = "https://github.com/BaseModelAI/pkq"
+Issues = "https://github.com/BaseModelAI/pkq/issues"
+Releases = "https://github.com/BaseModelAI/pkq/releases"
+
 [project.optional-dependencies]
 dev = [
   "pytest>=8.0",

scripts/release.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+VERSION_PATTERN = re.compile(r"\b\d+\.\d+\.\d+\b")
+
+TARGETS = [
+    REPO_ROOT / "Cargo.toml",
+    REPO_ROOT / "pyproject.toml",
+    REPO_ROOT / "scripts" / "render_sexy_hero.py",
+]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Bump pqk version metadata, optionally commit, tag, and push a release."
+    )
+    parser.add_argument("version", help="SemVer version number, for example 1.0.1")
+    parser.add_argument("--commit", action="store_true", help="Create a git commit for the version bump")
+    parser.add_argument("--tag", action="store_true", help="Create an annotated git tag v<version>")
+    parser.add_argument("--push", action="store_true", help="Push main and tags to the selected remote")
+    parser.add_argument("--remote", default="origin", help="Git remote to push to when --push is set")
+    return parser.parse_args()
+
+
+def validate_version(version: str) -> None:
+    if not re.fullmatch(r"\d+\.\d+\.\d+", version):
+        raise SystemExit(f"invalid version '{version}', expected SemVer like 1.0.1")
+
+
+def run(*args: str) -> None:
+    subprocess.run(args, cwd=REPO_ROOT, check=True)
+
+
+def replace_version(path: Path, version: str) -> None:
+    original = path.read_text()
+    updated, count = VERSION_PATTERN.subn(version, original, count=1)
+    if count != 1:
+        raise SystemExit(f"could not update version in {path}")
+    path.write_text(updated)
+
+
+def main() -> None:
+    args = parse_args()
+    validate_version(args.version)
+
+    for path in TARGETS:
+        replace_version(path, args.version)
+
+    if args.commit:
+        run("git", "add", *(str(path.relative_to(REPO_ROOT)) for path in TARGETS))
+        run("git", "commit", "-m", f"Release v{args.version}")
+
+    if args.tag:
+        run("git", "tag", "-a", f"v{args.version}", "-m", f"Release v{args.version}")
+
+    if args.push:
+        run("git", "push", args.remote, "main")
+        run("git", "push", args.remote, "--tags")
+
+    print(f"updated version metadata to {args.version}")
+
+
+if __name__ == "__main__":
+    main()