chore: add prerelease stamping workflow

Author: rgbkrk

.github/workflows/stamp-prerelease.yml

@@ -0,0 +1,59 @@
+name: Stamp Prerelease Version
+
+on:
+  workflow_dispatch:
+    inputs:
+      base_version:
+        description: Stable base version to stamp, e.g. 2.0.1
+        required: true
+        default: "2.0.1"
+      timestamp:
+        description: Optional UTC timestamp in YYYYMMDDHHMM form
+        required: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  stamp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Stamp prerelease version
+        id: stamp
+        run: |
+          args=(--base-version "${{ inputs.base_version }}")
+          if [ -n "${{ inputs.timestamp }}" ]; then
+            args+=(--timestamp "${{ inputs.timestamp }}")
+          fi
+
+          version=$(python scripts/set_prerelease_version.py "${args[@]}")
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Refresh lockfile
+        run: uv lock
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          branch: chore/stamp-prerelease-${{ steps.stamp.outputs.version }}
+          delete-branch: true
+          commit-message: chore: stamp prerelease version ${{ steps.stamp.outputs.version }}
+          title: chore: stamp prerelease version ${{ steps.stamp.outputs.version }}
+          body: |
+            Stamps `pyproject.toml` and `uv.lock` for the next prerelease publish.
+
+            Next steps:
+            - merge this PR to `main`
+            - create a GitHub prerelease from `main`
+            - let `publish.yml` push the prerelease to PyPI

README.md

@@ -105,6 +105,7 @@ claude mcp add nteract -- env RUNTIMED_SOCKET_PATH="$HOME/Library/Caches/runt-ni
 
 - `main` publishes prerelease `nteract` builds for the 2.x transition and tracks `runtimed 2.x` prereleases.
 - `release/1.9.x` is the stable maintenance line for desktop `1.4.x` and stays on `runtimed 1.9.0`.
+- use the `Stamp Prerelease Version` GitHub Actions workflow to open a PR with the next `2.x` prerelease version before publishing from `main`
 
 ## Available Tools
 

scripts/set_prerelease_version.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Stamp the project with a PEP 440 prerelease version."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--base-version",
+        required=True,
+        help="Stable base version in X.Y.Z form, e.g. 2.0.1",
+    )
+    parser.add_argument(
+        "--timestamp",
+        help="UTC timestamp suffix in YYYYMMDDHHMM form. Defaults to current UTC minute.",
+    )
+    return parser.parse_args()
+
+
+def build_version(base_version: str, timestamp: str | None) -> str:
+    if not re.fullmatch(r"\d+\.\d+\.\d+", base_version):
+        raise SystemExit(f"Invalid base version '{base_version}'. Expected X.Y.Z.")
+
+    if timestamp is None:
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d%H%M")
+    elif not re.fullmatch(r"\d{12}", timestamp):
+        raise SystemExit(f"Invalid timestamp '{timestamp}'. Expected YYYYMMDDHHMM.")
+
+    return f"{base_version}a{timestamp}"
+
+
+def replace_version(pyproject_path: Path, version: str) -> None:
+    text = pyproject_path.read_text()
+    updated_text, count = re.subn(
+        r'(?m)^version = "[^"]+"$',
+        f'version = "{version}"',
+        text,
+        count=1,
+    )
+    if count != 1:
+        raise SystemExit(f"Could not update version in {pyproject_path}")
+    pyproject_path.write_text(updated_text)
+
+
+def main() -> None:
+    args = parse_args()
+    version = build_version(args.base_version, args.timestamp)
+    replace_version(Path("pyproject.toml"), version)
+    print(version)
+
+
+if __name__ == "__main__":
+    main()