feat(release): add support for manual version input in workflow dispatch

Author: markhazleton

.github/workflows/release.yml

@@ -9,6 +9,11 @@ on:
       - 'templates/**'
       - '.github/workflows/**'
   workflow_dispatch:
+    inputs:
+      release_version:
+        description: 'Optional release version (e.g., 1.4.6 or v1.4.6). If omitted, workflow auto-selects.'
+        required: false
+        type: string
 
 jobs:
   release:
@@ -26,7 +31,7 @@ jobs:
         id: get_tag
         run: |
           chmod +x .github/workflows/scripts/get-next-version.sh
-          .github/workflows/scripts/get-next-version.sh
+          .github/workflows/scripts/get-next-version.sh "${{ github.event.inputs.release_version || '' }}"
       - name: Check if release already exists
         id: check_release
         run: |

.github/workflows/scripts/get-next-version.sh

@@ -2,26 +2,66 @@
 set -euo pipefail
 
 # get-next-version.sh
-# Calculate the next version based on the latest git tag and output GitHub Actions variables
-# Usage: get-next-version.sh
+# Calculate release version and output GitHub Actions variables
+# Usage: get-next-version.sh [explicit_version]
 # Uses standard semantic versioning (MAJOR.MINOR.PATCH)
 
 # Get the latest tag, or use v0.0.0 if no tags exist
 LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
 echo "latest_tag=$LATEST_TAG" >> $GITHUB_OUTPUT
 
-# Parse semantic version
-if [[ $LATEST_TAG =~ ^v([0-9]+)\.([0-9]+)\.([0-9]+) ]]; then
-  # Increment patch version
-  MAJOR=${BASH_REMATCH[1]}
-  MINOR=${BASH_REMATCH[2]}
-  PATCH=${BASH_REMATCH[3]}
-  PATCH=$((PATCH + 1))
-  NEW_VERSION="v$MAJOR.$MINOR.$PATCH"
-else
-  # First release - start with v1.0.0
-  NEW_VERSION="v1.0.0"
+EXPLICIT_VERSION="${1:-}"
+
+normalize_version() {
+  local raw="$1"
+  raw="${raw#v}"
+  if [[ $raw =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    echo "v$raw"
+    return 0
+  fi
+  return 1
+}
+
+increment_patch() {
+  local tag="$1"
+  if [[ $tag =~ ^v([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+    local major="${BASH_REMATCH[1]}"
+    local minor="${BASH_REMATCH[2]}"
+    local patch="${BASH_REMATCH[3]}"
+    patch=$((patch + 1))
+    echo "v$major.$minor.$patch"
+    return 0
+  fi
+  echo "v1.0.0"
+}
+
+# 1) Explicit manual input wins (workflow_dispatch input)
+if [[ -n "$EXPLICIT_VERSION" ]]; then
+  if NEW_VERSION=$(normalize_version "$EXPLICIT_VERSION"); then
+    echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+    echo "New version will be: $NEW_VERSION (source: explicit input)"
+    exit 0
+  else
+    echo "Invalid explicit version '$EXPLICIT_VERSION'. Use MAJOR.MINOR.PATCH (optionally prefixed with v)." >&2
+    exit 1
+  fi
 fi
 
+# 2) Prefer pyproject.toml version when present and not already tagged
+if [[ -f "pyproject.toml" ]]; then
+  PYPROJECT_VERSION=$(grep -oE '^[[:space:]]*version[[:space:]]*=[[:space:]]*"[0-9]+\.[0-9]+\.[0-9]+"' pyproject.toml | head -n1 | sed -E 's/.*"([0-9]+\.[0-9]+\.[0-9]+)"/\1/')
+  if [[ -n "${PYPROJECT_VERSION:-}" ]]; then
+    CANDIDATE_VERSION="v$PYPROJECT_VERSION"
+    if ! git rev-parse -q --verify "refs/tags/$CANDIDATE_VERSION" >/dev/null 2>&1; then
+      echo "new_version=$CANDIDATE_VERSION" >> $GITHUB_OUTPUT
+      echo "New version will be: $CANDIDATE_VERSION (source: pyproject.toml)"
+      exit 0
+    fi
+  fi
+fi
+
+# 3) Fallback: increment latest tag
+NEW_VERSION=$(increment_patch "$LATEST_TAG")
+
 echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
-echo "New version will be: $NEW_VERSION"
+echo "New version will be: $NEW_VERSION (source: latest tag increment)"

templates/commands/release.md

@@ -376,6 +376,12 @@ Confirm these three sources agree on {NEXT_VERSION}:
 
 If any are out of sync, fix before tagging.
 
+#### D. Manual workflow dispatch version (recommended)
+
+When running **Create Release** via `workflow_dispatch`, set `release_version` to
+`{NEXT_VERSION}` (or `v{NEXT_VERSION}`) so the workflow publishes the intended tag
+instead of auto-incrementing from the latest existing tag.
+
 ### 10. Clean Slate Preparation
 
 After archival (skip if DRY_RUN):