Merge pull request #17 from aerospike-community/fix/release-pypi-metadata-guard

ci: guard PyPI metadata and document retagging

Author: lyndonbauto

.github/workflows/release.yml

@@ -84,6 +84,9 @@ jobs:
       - name: Build sdist and wheel
         run: python -m pip install build && python -m build
 
+      - name: Validate PyPI-compatible metadata
+        run: python scripts/validate_pypi_metadata.py
+
       - name: Upload distributions
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:

RELEASING.md

@@ -44,11 +44,20 @@ In https://github.com/aerospike-community/adk-aerospike/settings/environments:
 1. Bump version in **both** `pyproject.toml` and `src/adk_aerospike/__init__.py`.
 2. Update `CHANGELOG.md`.
 3. Merge to `main`.
-4. Tag and push:
+4. Tag the **current `main` HEAD** (after your release PR is merged) and push:
 
    ```bash
-   git tag v0.0.1
-   git push origin v0.0.1
+   git checkout main && git pull
+   git tag v0.0.2
+   git push origin v0.0.2
+   ```
+
+   If a tag already exists on an older commit, delete it locally and on GitHub before re-tagging:
+
+   ```bash
+   git tag -d v0.0.2
+   git push origin :refs/tags/v0.0.2
+   git tag v0.0.2 && git push origin v0.0.2
    ```
 
 5. In GitHub Actions, open the **Release** workflow run; approve the **pypi** environment deployment if reviewers are configured.
@@ -71,14 +80,19 @@ In https://github.com/aerospike-community/adk-aerospike/settings/environments:
 ```bash
 python -m pip install build
 python -m build
+python scripts/validate_pypi_metadata.py
 pip install dist/adk_aerospike-*.whl
 ```
 
+Benchmark harness deps are **not** in the PyPI package — install with `pip install -r benchmarks/requirements.txt`.
+
 ## Troubleshooting
 
 | Symptom | Likely cause |
 | --- | --- |
 | Publish job fails immediately on OIDC | Trusted publisher owner/repo/workflow/environment mismatch |
 | “File already exists” on upload | Version not bumped; PyPI versions are immutable |
 | Tag/job fails at version check | Tag `v0.0.2` but `pyproject.toml` still `0.0.1` |
+| `400 Can't have direct dependency` on upload | Tag points at a commit before the fix, or `[benchmark]` / git URL still in `pyproject.toml`; run `python scripts/validate_pypi_metadata.py` after `python -m build` |
+| Validate step fails on release | Wheel still embeds VCS deps — remove optional extras with git URLs from `pyproject.toml` |
 | Environment never appears | Workflow must reference `environment: name: pypi` on the publish job |

scripts/validate_pypi_metadata.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Fail if built wheel/sdist metadata contains PyPI-forbidden VCS direct deps."""
+
+from __future__ import annotations
+
+import sys
+import zipfile
+from pathlib import Path
+
+
+def _check_metadata(text: str, label: str) -> list[str]:
+    errors: list[str] = []
+    if "git+" in text or " @ git" in text:
+        errors.append(f"{label}: VCS/direct URL dependency in metadata")
+    if "Extra: benchmark" in text and "ai-ecosystem-benchmark" in text:
+        errors.append(f"{label}: [benchmark] extra still in metadata (use benchmarks/requirements.txt)")
+    return errors
+
+
+def main() -> int:
+    dist = Path("dist")
+    if not dist.is_dir():
+        print("dist/ not found; run python -m build first", file=sys.stderr)
+        return 1
+
+    errors: list[str] = []
+    for whl in sorted(dist.glob("*.whl")):
+        with zipfile.ZipFile(whl) as zf:
+            meta_name = next(n for n in zf.namelist() if n.endswith(".dist-info/METADATA"))
+            errors.extend(_check_metadata(zf.read(meta_name).decode(), whl.name))
+
+    if errors:
+        for err in errors:
+            print(err, file=sys.stderr)
+        return 1
+
+    print("PyPI metadata OK")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())