Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 129 additions & 0 deletions .github/scripts/classify-commits.py
Original file line number Diff line number Diff line change
@@ -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 "<none>")
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 "version<TAB>notes_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", "<none>").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 == "<none>":
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 != "<none>":
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())
108 changes: 108 additions & 0 deletions .github/scripts/cut-release.sh
Original file line number Diff line number Diff line change
@@ -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="<none>"
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 "version<TAB>notes_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}"
71 changes: 71 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -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
17 changes: 16 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Loading