From df82f00758a245cf3970e6447b04e242c00aa15f Mon Sep 17 00:00:00 2001 From: sabith Date: Wed, 11 Nov 2026 12:00:38 -0800 Subject: [PATCH] Automate versioned releases behind a green-Self-test gate Releases were cut by hand (tag, release notes, moving v1 tag). The new Release workflow (workflow_dispatch on main) refuses to release unless Self-test is green for the exact commit, derives the next version from conventional-commit subjects since the last tag when no explicit version is given (feat or breaking -> minor, fix -> patch; breaking bumps minor on the 0.x line), re-points the v1 moving tag, and publishes grouped notes. cut-release.sh has a --dry-run mode for local preview; the dry run against current main derives v0.2.0 (first use: publish PR #2). --- .github/scripts/classify-commits.py | 129 ++++++++++++++++++++++++++++ .github/scripts/cut-release.sh | 108 +++++++++++++++++++++++ .github/workflows/release.yml | 71 +++++++++++++++ README.md | 17 +++- 4 files changed, 324 insertions(+), 1 deletion(-) create mode 100644 .github/scripts/classify-commits.py create mode 100755 .github/scripts/cut-release.sh create mode 100644 .github/workflows/release.yml diff --git a/.github/scripts/classify-commits.py b/.github/scripts/classify-commits.py new file mode 100644 index 0000000..b9e80ec --- /dev/null +++ b/.github/scripts/classify-commits.py @@ -0,0 +1,129 @@ +#!/usr/bin/env python3 +"""Classify commit subjects and derive the next version + release notes. + +Reads commit subjects on stdin (one per line). Env: + CUT_LAST_TAG previous tag, e.g. v0.1.1 (may be "") + CUT_VERSION_OVERRIDE explicit version; when set, only notes are generated + CUT_NOTES_LINE optional one-line summary for the top of the notes + +Prints "versionnotes_path" on the last line; classification goes to +stderr so operators can see how the bump was chosen. + +Classification (first match wins, per subject): + conventional "!:" suffix or "BREAKING CHANGE" -> breaking + conventional "feat"/"feature" -> minor + conventional "fix" -> patch + keyword fallback in the subject text: + breaking -> breaking + feat/feature -> minor + add/new/support/introduce -> minor + fix/fixes/bugfix -> patch + anything else -> other + +Bump choice for the derived version (0.x line: breaking bumps minor, not +major, matching this repo's v0.x releases under the v1 moving tag): + any breaking or minor -> minor bump + otherwise -> patch bump +""" + +import os +import re +import sys +import tempfile + +CONVENTIONAL = re.compile(r"^(\w+)(?:\([^)]*\))?(!)?:", re.IGNORECASE) + + +def classify(subject: str) -> str: + text = subject.strip() + if not text: + return "other" + m = CONVENTIONAL.match(text) + if m: + kind, breaking = m.group(1).lower(), bool(m.group(2)) + if breaking or "BREAKING CHANGE" in text.upper(): + return "breaking" + if kind in ("feat", "feature"): + return "minor" + if kind == "fix": + return "patch" + return "other" + low = text.lower() + if "breaking change" in low: + return "breaking" + if re.search(r"\b(feat|feature)\b", low): + return "minor" + if re.search(r"\b(add|adds|added|new|support|supports|introduce|introduces)\b", low): + return "minor" + if re.search(r"\b(fix|fixes|fixed|bugfix)\b", low): + return "patch" + return "other" + + +def bump_version(last: str, kinds: set) -> str: + m = re.match(r"v?(\d+)\.(\d+)\.(\d+)", last) + major, minor, patch = (int(m.group(i)) for i in (1, 2, 3)) + if "breaking" in kinds or "minor" in kinds: + minor, patch = minor + 1, 0 + else: + patch += 1 + return f"v{major}.{minor}.{patch}" + + +def main() -> int: + last_tag = os.environ.get("CUT_LAST_TAG", "").strip() + override = os.environ.get("CUT_VERSION_OVERRIDE", "").strip() + notes_line = os.environ.get("CUT_NOTES_LINE", "").strip() + + subjects = [line.rstrip("\n") for line in sys.stdin if line.strip()] + # Merge commits ("Merge pull request #N ...") carry no signal of their own; + # the squashed/PR subjects do. Keep them for notes, but they classify as + # "other" unless the branch name inside mentions fix/feat. + kinds = set() + groups: dict = {"minor": [], "patch": [], "other": []} + for subject in subjects: + kind = classify(subject) + kinds.add(kind) + if kind == "breaking": + groups["minor"].append(subject) # 0.x line reports breaking as minor + elif kind in groups: + groups[kind].append(subject) + + if override: + version = override + elif last_tag == "": + version = "" + else: + version = bump_version(last_tag, kinds) + + print(f"classification: kinds={sorted(kinds)} subjects={len(subjects)}", file=sys.stderr) + + notes = ["# What changed\n"] + if notes_line: + notes.append(f"{notes_line}\n") + if last_tag != "": + notes.append(f"## Changes since {last_tag}\n") + section_titles = [("minor", "Features"), ("patch", "Fixes"), ("other", "Other")] + for key, title in section_titles: + if not groups[key]: + continue + notes.append(f"### {title}\n") + for subject in groups[key]: + notes.append(f"- {subject}") + notes.append("") + notes.append( + "Use the moving major tag (`uses: stackgenhq/cce-action@v1`) or pin the exact " + f"release (`uses: stackgenhq/cce-action@{version or 'vX.Y.Z'}`).\n" + ) + + with tempfile.NamedTemporaryFile( + "w", suffix=".md", prefix="release-notes-", delete=False + ) as fh: + fh.write("\n".join(notes)) + path = fh.name + print(f"{version}\t{path}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.github/scripts/cut-release.sh b/.github/scripts/cut-release.sh new file mode 100755 index 0000000..e9a4d20 --- /dev/null +++ b/.github/scripts/cut-release.sh @@ -0,0 +1,108 @@ +#!/usr/bin/env bash +# cut-release.sh — cut a versioned release of cce-action. +# +# Called by .github/workflows/release.yml after Self-test is green on main. +# Also runnable locally with --dry-run for a preview: +# +# GITHUB_REPOSITORY=stackgenhq/cce-action GITHUB_SHA=$(git rev-parse HEAD) \ +# bash .github/scripts/cut-release.sh --dry-run +# +# Behavior: +# 1. version = RELEASE_VERSION override, else derived from commit subjects +# since the last reachable tag: conventional feat!/!:/BREAKING or feat -> +# minor (0.x line: breaking bumps minor, not major), conventional fix -> +# patch, keyword fallback (add/new/support -> minor, fix -> patch), else +# patch. +# 2. release notes = NOTES_LINE + commit subjects grouped by that same +# classification. +# 3. tags the target SHA, pushes the tag, re-points MAJOR_TAG (default v1) +# at it (best effort: a tag-protection rule may forbid the force push, +# which must not fail the release), and creates the GitHub release. +# +# Required env: GITHUB_REPOSITORY, GITHUB_SHA (release target). +# Optional env: RELEASE_VERSION, MAJOR_TAG, NOTES_LINE, GH_TOKEN (push/release). +set -euo pipefail + +dry_run=false +if [ "${1:-}" = "--dry-run" ]; then + dry_run=true +fi + +: "${GITHUB_REPOSITORY:?GITHUB_REPOSITORY is required}" +: "${GITHUB_SHA:?GITHUB_SHA (release target) is required}" +sha="$GITHUB_SHA" +version="${RELEASE_VERSION:-}" +major_tag="${MAJOR_TAG:-v1}" +notes_line="${NOTES_LINE:-}" +ref_name="${GITHUB_REF_NAME:-$(git rev-parse --abbrev-ref HEAD)}" + +cd "$(git rev-parse --show-toplevel)" + +if ! git rev-parse -q --verify "${sha}^{commit}" >/dev/null; then + echo "::error::commit ${sha} not present in this checkout; fetch it first" >&2 + exit 1 +fi + +last_tag=$(git describe --tags --abbrev=0 "${sha}" 2>/dev/null || true) +if [ -z "$last_tag" ]; then + if [ -z "$version" ]; then + echo "::error::no previous tag to derive from; set RELEASE_VERSION explicitly" >&2 + exit 1 + fi + last_tag="" +fi +range="${last_tag}..${sha}" + +# subjects one per line; python classifies and derives version + notes. +export CUT_LAST_TAG="$last_tag" +export CUT_VERSION_OVERRIDE="$version" +export CUT_NOTES_LINE="$notes_line" +derived=$(git log --format='%s' "$range" | python3 .github/scripts/classify-commits.py) +# classify-commits.py prints "versionnotes_path" on the last line. +version=$(printf '%s' "$derived" | tail -1 | cut -f1) +notes_path=$(printf '%s' "$derived" | tail -1 | cut -f2) + +if [ -z "$version" ]; then + echo "::error::could not derive a version" >&2 + exit 1 +fi +if git rev-parse -q --verify "refs/tags/$version" >/dev/null; then + echo "::error::tag $version already exists; pass a fresh RELEASE_VERSION" >&2 + exit 1 +fi + +echo "Release plan:" +echo " target: ${sha} (${ref_name})" +echo " version: ${version}" +echo " since: ${last_tag}" +if [ -n "$major_tag" ]; then + echo " major tag: ${major_tag} -> ${version} (best effort)" +fi +echo " notes:" +sed 's/^/ /' "$notes_path" +echo + +if [ "$dry_run" = true ]; then + echo "dry run; nothing tagged or pushed" + exit 0 +fi + +: "${GH_TOKEN:?GH_TOKEN is required to push tags and create the release}" +git tag -a "$version" -m "Release $version" "$sha" +git push origin "refs/tags/$version" + +if [ -n "$major_tag" ]; then + if git tag -fa "$major_tag" -m "Moving $major_tag to $version" "$sha" \ + && git push --force origin "refs/tags/$major_tag"; then + echo "moved ${major_tag} to ${version}" + else + echo "::warning::could not re-point ${major_tag} (tag protection rule?); the release ${version} is still published. Update the moving tag manually if needed." + fi +fi + +gh release create "$version" \ + --repo "$GITHUB_REPOSITORY" \ + --verify-tag \ + --title "$version" \ + --notes-file "$notes_path" +echo "released ${version}" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..cbbb63c --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,71 @@ +name: Release + +# Cuts a versioned release of cce-action. Run from the Actions tab on main: +# "Run workflow" with an optional explicit version (e.g. v0.2.0); when left +# empty the version is derived from the commit subjects since the last tag +# (.github/scripts/classify-commits.py). The moving major tag (v1 by default) +# is re-pointed at the release (best effort). +# +# The release refuses to run unless a Self-test run is green for the exact +# commit being released, so a red main can never ship a tag. +on: + workflow_dispatch: + inputs: + version: + description: "Version to cut (e.g. v0.2.0). Empty = derive from commits since the last tag." + required: false + default: "" + major-tag: + description: "Moving major tag to re-point at the release (empty skips)." + required: false + default: "v1" + notes: + description: "Optional one-line summary at the top of the release notes." + required: false + default: "" + +permissions: + contents: write + actions: read + +concurrency: + group: release + cancel-in-progress: false + +jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Require a green Self-test for the release target + env: + GH_TOKEN: ${{ github.token }} + RELEASE_SHA: ${{ github.sha }} + run: | + set -euo pipefail + green=$(gh api "repos/${GITHUB_REPOSITORY}/actions/runs?head_sha=${RELEASE_SHA}&per_page=100" \ + --jq '[.workflow_runs[] | select(.name == "Self-test" and .conclusion == "success")] | length') + if [ "$green" -lt 1 ]; then + echo "::error::No successful Self-test run for ${GITHUB_REPOSITORY}@${RELEASE_SHA}. Re-run Self-test on main before releasing." + exit 1 + fi + echo "Self-test is green for ${RELEASE_SHA}." + + - name: Checkout + uses: actions/checkout@v4 + with: + # Full history: version derivation and notes need the commits since + # the last tag. + fetch-depth: 0 + ref: ${{ github.sha }} + + - name: Cut release + env: + GH_TOKEN: ${{ github.token }} + GITHUB_SHA: ${{ github.sha }} + GITHUB_REF_NAME: main + RELEASE_VERSION: ${{ inputs.version }} + MAJOR_TAG: ${{ inputs.major-tag }} + NOTES_LINE: ${{ inputs.notes }} + run: | + set -euo pipefail + bash .github/scripts/cut-release.sh diff --git a/README.md b/README.md index df6b53b..8cdb2df 100644 --- a/README.md +++ b/README.md @@ -108,4 +108,19 @@ or checking the repo size in a prior step. ## Versioning -Use a major tag (`@v1`) or a pinned release (`@v0.1.0`). Tags are published after self-test CI is green. Pin `image` to a version tag (for example `ghcr.io/stackgenhq/cce:0.0.12`) when you need a fixed CLI. +Use a major tag (`@v1`) or a pinned release (`@v0.2.0`). Pin `image` to a version tag (for example `ghcr.io/stackgenhq/cce:0.0.12`) when you need a fixed CLI. + +Releases are cut from the **Release** workflow (Actions tab -> Run workflow on +`main`). The workflow refuses to release unless Self-test is green for the +exact commit being released. Leave the version input empty and the next +version is derived from the commit subjects since the last tag +(`feat`/`feat!` -> minor bump, `fix` -> patch bump; on the 0.x line a breaking +change bumps minor, not major), or pass an explicit version like `v0.2.0`. +The moving major tag (`v1` by default) is re-pointed at the release, and the +release notes list the classified commits. The same logic can be previewed +locally: + +```bash +GITHUB_REPOSITORY=stackgenhq/cce-action GITHUB_SHA=$(git rev-parse HEAD) \ + bash .github/scripts/cut-release.sh --dry-run +```