feat: releases workflow

Minibrams · Minibrams · commit 4d1c45d7a828 · 2026-04-24T01:25:44.000Z
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,108 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - releases
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Sync packages
+        run: uv sync --locked --all-packages
+
+      - name: Resolve release version
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          import sys
+          import tomllib
+          from pathlib import Path
+
+          with open("pyproject.toml", "rb") as file:
+              version = tomllib.load(file)["project"]["version"]
+
+          if not re.fullmatch(r"\d+\.\d+\.\d+((a|b|rc)\d+)?", version):
+              print(f"Unsupported release version: {version!r}")
+              print("Expected X.Y.Z, X.Y.ZaN, X.Y.ZbN, or X.Y.ZrcN.")
+              sys.exit(1)
+
+          tag = f"v{version}"
+          github_env = Path(os.environ["GITHUB_ENV"])
+          with github_env.open("a") as env:
+              env.write(f"RELEASE_VERSION={version}\n")
+              env.write(f"TAG_NAME={tag}\n")
+          PY
+
+      - name: Verify release tag is new
+        run: |
+          if git rev-parse --verify --quiet "refs/tags/$TAG_NAME"; then
+              echo "Tag $TAG_NAME already exists."
+              exit 1
+          fi
+          if git ls-remote --exit-code --tags origin "refs/tags/$TAG_NAME" >/dev/null 2>&1; then
+              echo "Tag $TAG_NAME already exists on origin."
+              exit 1
+          fi
+
+      - name: Check import sorting
+        run: uv run ruff check --select I .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run basedpyright .
+
+      - name: Contract tests
+        run: uv run pytest tests/test_contracts.py -n auto
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Check distributions
+        run: uv run twine check dist/*
+
+      - name: Create release tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG_NAME" -m "Release $TAG_NAME" "$GITHUB_SHA"
+          git push origin "$TAG_NAME"
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$TAG_NAME" dist/* --generate-notes --title "$TAG_NAME"
diff --git a/README.md b/README.md
@@ -77,6 +77,30 @@ result = generate_client(
 
 Invalid extension outputs fail fast with explicit diagnostics.
 
+## Releases
+
+Releases are published from the protected `releases` branch. The package version is set manually in `pyproject.toml`, and pushing a release commit to `releases` triggers the GitHub Actions release workflow. The workflow creates the matching `vX.Y.Z` tag after checks pass.
+
+Before the first release, configure PyPI Trusted Publishing for this repository:
+
+- PyPI project: `openapi-python`
+- GitHub workflow: `release.yml`
+- GitHub environment: `pypi`
+
+The GitHub `pypi` environment should be limited to deployments from the `releases` branch.
+
+Release steps:
+
+```bash
+# 1. Update project.version in pyproject.toml, then commit that change.
+uv run python scripts/release.py --version 0.1.0
+
+# 2. If checks pass, push the current commit to the releases branch.
+uv run python scripts/release.py --version 0.1.0 --push-release-branch
+```
+
+The release workflow verifies that the version tag does not already exist, runs checks, builds the distributions, validates them with `twine`, creates the release tag, publishes to PyPI, and creates a GitHub Release with generated notes.
+
 ## Transport Decoupling
 
 Generated clients expose a transport protocol. You can plug in your own transport while keeping route-level typing guarantees.
diff --git a/scripts/release.py b/scripts/release.py
@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import tomllib
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def run(
+    command: list[str], *, capture: bool = False
+) -> subprocess.CompletedProcess[str]:
+    print("+", " ".join(command))
+    return subprocess.run(
+        command,
+        cwd=ROOT,
+        check=True,
+        text=True,
+        stdout=subprocess.PIPE if capture else None,
+        stderr=subprocess.PIPE if capture else None,
+    )
+
+
+def project_version() -> str:
+    with (ROOT / "pyproject.toml").open("rb") as file:
+        return tomllib.load(file)["project"]["version"]
+
+
+def require_supported_version(version: str) -> None:
+    if not re.fullmatch(r"\d+\.\d+\.\d+((a|b|rc)\d+)?", version):
+        print(f"Unsupported release version: {version!r}")
+        print("Expected X.Y.Z, X.Y.ZaN, X.Y.ZbN, or X.Y.ZrcN.")
+        sys.exit(1)
+
+
+def require_clean_worktree() -> None:
+    status = run(["git", "status", "--porcelain"], capture=True).stdout.strip()
+    if status:
+        print(
+            "Release requires a clean git worktree. Commit or stash these changes first:"
+        )
+        print(status)
+        sys.exit(1)
+
+
+def require_tag_available(tag: str) -> None:
+    local = subprocess.run(
+        ["git", "rev-parse", "--verify", "--quiet", f"refs/tags/{tag}"],
+        cwd=ROOT,
+        text=True,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    if local.returncode == 0:
+        print(f"Tag {tag} already exists locally.")
+        sys.exit(1)
+
+    remote = subprocess.run(
+        ["git", "ls-remote", "--exit-code", "--tags", "origin", f"refs/tags/{tag}"],
+        cwd=ROOT,
+        text=True,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    if remote.returncode == 0:
+        print(f"Tag {tag} already exists on origin.")
+        sys.exit(1)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Prepare and optionally publish from the releases branch."
+    )
+    parser.add_argument(
+        "--version",
+        help="Expected version. Defaults to the version in pyproject.toml.",
+    )
+    parser.add_argument(
+        "--push-release-branch",
+        action="store_true",
+        help="Push the current commit to origin/releases after release checks pass.",
+    )
+    args = parser.parse_args()
+
+    version = project_version()
+    require_supported_version(version)
+    if args.version and args.version != version:
+        print(
+            f"Expected version {args.version}, but pyproject.toml contains {version}."
+        )
+        sys.exit(1)
+
+    tag = f"v{version}"
+
+    require_clean_worktree()
+    require_tag_available(tag)
+
+    dist = ROOT / "dist"
+    if dist.exists():
+        shutil.rmtree(dist)
+
+    run(["uv", "run", "ruff", "check", "--select", "I", "."])
+    run(["uv", "run", "ruff", "format", "--check", "."])
+    run(["uv", "run", "basedpyright", "."])
+    run(["uv", "run", "pytest", "tests/test_contracts.py", "-n", "auto"])
+    run(["uv", "build"])
+    run(["uv", "run", "twine", "check", *sorted(str(path) for path in dist.iterdir())])
+
+    if args.push_release_branch:
+        run(["git", "push", "origin", "HEAD:releases"])
+        print("Pushed current commit to origin/releases.")
+        print("GitHub Actions will create the release tag and publish after approval.")
+    else:
+        print(f"Release checks passed for {tag}.")
+        print("Publish with: git push origin HEAD:releases")
+
+
+if __name__ == "__main__":
+    main()
