feat: add reusable release workflow

.github/actions/check-release-notes/action.yml

@@ -0,0 +1,24 @@
+name: Check release notes
+description: Fail when commits in a range would be missing from the git-cliff notes.
+inputs:
+  range:
+    description: Git range to check, for example v0.3.0..HEAD.
+    required: true
+  force:
+    description: Warn instead of failing when commits are missing.
+    required: false
+    default: 'false'
+  context:
+    description: Path to the git-cliff --context JSON.
+    required: false
+    default: ctx.json
+runs:
+  using: composite
+  steps:
+    - name: Check release notes
+      shell: bash
+      env:
+        RANGE: ${{ inputs.range }}
+        FORCE: ${{ inputs.force }}
+        CLIFF_CONTEXT: ${{ inputs.context }}
+      run: bash "$GITHUB_ACTION_PATH/check-release-notes.sh" "$RANGE"

.github/actions/check-release-notes/check-release-notes.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+#
+# Lists the commits in a range that will not appear in the generated release
+# notes, and fails unless FORCE is true. Prints nothing and exits 0 when the
+# range is fully representable.
+#
+#   check-release-notes.sh v0.3.0..HEAD
+#
+# Expects the git-cliff context in $CLIFF_CONTEXT (default: ctx.json), produced
+# by:
+#
+#   git cliff --config <cliff.toml> --use-branch-tags --unreleased --bump --context
+#
+# A commit reaches the notes only if both of these hold:
+#
+#   1. it is a merge commit, because the shared cliff.toml filters on merge_commit
+#   2. its subject parses as a conventional commit, which is what picks a group
+#
+# The context check keeps a config that groups extra types from stopping the
+# release: if git-cliff renders the merge, the notes contain it.
+#
+# Squash and rebase merges fail the first. GitHub's default
+# "Merge pull request #1 from ..." subject and the Revert button's default
+# title fail the second.
+
+set -euo pipefail
+
+RANGE="${1:?usage: $0 <git range>, e.g. v0.3.0..HEAD}"
+CLIFF_CONTEXT="${CLIFF_CONTEXT:-ctx.json}"
+FORCE="${FORCE:-false}"
+
+# The conventional types the shared cliff.toml groups or deliberately skips.
+# Anything else has no section to go into and is dropped.
+CONVENTIONAL_TYPES='feat|fix|perf|refactor|revert|docs|ci|chore|test|style|build'
+
+# git-cliff strips these before parsing and trims the subject, so they have to
+# go here too, otherwise a subject like "✨ feat: thing" looks unparseable when
+# git-cliff handles it fine. Keep in sync with commit_preprocessors in the
+# shared cliff.toml at the repository root. A caller that overrides
+# `cliff_config` gets a best-effort check; the rendered context above remains
+# authoritative for merges it actually renders.
+EMOJI_RANGES='\x{1F000}-\x{1FAFF}\x{2600}-\x{27BF}\x{2B00}-\x{2BFF}\x{FE0E}\x{FE0F}\x{200D}'
+
+normalise_subjects() {
+  perl -CSD -pe "s/[${EMOJI_RANGES}]//g; s/[ \\t]{2,}/ /g; s/^[ \\t]+//; s/[ \\t]+$//"
+}
+
+# Commits git-cliff will render. The notes template keeps merge commits only,
+# so a non-merge that protect_breaking_commits puts in the context is not
+# rendered and must still be reported.
+rendered_ids=$(jq -r '.[0].commits[] | select(.merge_commit == true) | .id' "$CLIFF_CONTEXT")
+
+missing=$(
+  # \x1f is not IFS whitespace, so an empty %P (root commit) stays a field
+  # instead of collapsing and shifting the subject into parents.
+  git log --first-parent "$RANGE" --format='%H%x1f%h%x1f%P%x1f%s' |
+    while IFS=$'\x1f' read -r sha short parents subject; do
+      # Already represented in the notes.
+      if grep -qxF "$sha" <<< "$rendered_ids"; then
+        continue
+      fi
+
+      # A merge whose type the notes deliberately skip is not a missing
+      # commit. Non-merges never reach the notes, so they are reported
+      # whatever their type.
+      if [[ "$parents" == *" "* ]]; then
+        normalised=$(printf '%s' "$subject" | normalise_subjects)
+        if [[ "$normalised" =~ ^(${CONVENTIONAL_TYPES})(\(.+\))?!?: ]]; then
+          continue
+        fi
+      fi
+
+      printf '%s %s\n' "$short" "$subject"
+    done
+)
+
+if [ -z "$missing" ]; then
+  exit 0
+fi
+
+printf '%s\n' "$missing"
+
+if [ "$FORCE" != "true" ]; then
+  echo "::error::These commits would be missing from the release notes. Fix the history, or re-run with force to release without them." >&2
+  exit 1
+fi
+
+echo "::warning::Releasing without the commits above in the notes, because force is set." >&2

.github/actions/check-release-notes/test-check-release-notes.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+TESTDIR="$(mktemp -d)"
+trap 'rm -rf "$TESTDIR"' EXIT
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+new_repo() {
+  local dir="$1"
+  mkdir -p "$dir"
+  cd "$dir"
+  git init -q -b main
+  git config user.email test@example.com
+  git config user.name Test
+  git config commit.gpgsign false
+  git config tag.gpgsign false
+  git commit -q --allow-empty -m "chore: init"
+  git tag v0.1.0
+}
+
+merge_commit() {
+  local branch="$1"
+  local subject="$2"
+  local title="$3"
+  git checkout -q -b "$branch" main
+  git commit -q --allow-empty -m "$subject"
+  git checkout -q main
+  git merge -q --no-ff "$branch" -m "$title"
+  git rev-parse HEAD
+}
+
+# Mixed history: rendered and unrendered merges, a deliberately skipped type,
+# and direct commits on main.
+new_repo "$TESTDIR/mixed"
+
+feat_merge=$(merge_commit feat "feat: real feature" "feat: real feature (#1)")
+merge_commit test "test: thing" "test: skipped merge (#2)" > /dev/null
+weird_merge=$(merge_commit weird "whatever" "Weird title (#3)")
+deps_merge=$(merge_commit deps "deps: bump" "deps: bump (#4)")
+breaking_merge=$(merge_commit breaking "feat!: breaking" "feat!: breaking merge (#5)")
+
+# Conventional subject with emoji and extra whitespace, absent from the
+# context: normalisation must trim it so the type filter still skips it.
+merge_commit spaced "feat: spaced" "  ✨  feat:   spaced   feature  " > /dev/null
+
+git commit -q --allow-empty -m "fix: direct commit"
+fix_direct=$(git rev-parse HEAD)
+git commit -q --allow-empty -m "feat!: direct breaking commit"
+breaking_direct=$(git rev-parse HEAD)
+
+# The context also carries protected breaking non-merges. The notes template
+# renders merges only, so those must still be reported.
+jq -n \
+  --arg feat "$feat_merge" \
+  --arg deps "$deps_merge" \
+  --arg breaking "$breaking_merge" \
+  --arg direct_breaking "$breaking_direct" \
+  '[{commits: [
+    {id: $feat, merge_commit: true},
+    {id: $deps, merge_commit: true},
+    {id: $breaking, merge_commit: true},
+    {id: $direct_breaking, merge_commit: false}
+  ]}]' > ctx.json
+
+expected=$(
+  printf '%s %s\n' "$(git rev-parse --short "$breaking_direct")" "feat!: direct breaking commit"
+  printf '%s %s\n' "$(git rev-parse --short "$fix_direct")" "fix: direct commit"
+  printf '%s %s\n' "$(git rev-parse --short "$weird_merge")" "Weird title (#3)"
+)
+
+echo "=== Test 1: mixed history ==="
+set +e
+actual=$(CLIFF_CONTEXT=ctx.json bash "$ROOT/check-release-notes.sh" v0.1.0..HEAD 2> /dev/null)
+rc=$?
+set -e
+[ "$rc" -eq 1 ] || fail "expected exit 1, got $rc"
+[ "$actual" = "$expected" ] || fail "unexpected output:
+$actual"
+echo "PASS"
+
+echo "=== Test 2: force ==="
+set +e
+actual=$(FORCE=true CLIFF_CONTEXT=ctx.json bash "$ROOT/check-release-notes.sh" v0.1.0..HEAD 2> /dev/null)
+rc=$?
+set -e
+[ "$rc" -eq 0 ] || fail "expected exit 0, got $rc"
+[ "$actual" = "$expected" ] || fail "unexpected output:
+$actual"
+echo "PASS"
+
+# Clean history: the only commit since the tag is rendered.
+new_repo "$TESTDIR/clean"
+clean_merge=$(merge_commit feat "feat: only feature" "feat: only feature (#1)")
+jq -n --arg id "$clean_merge" '[{commits: [{id: $id, merge_commit: true}]}]' > ctx.json
+
+echo "=== Test 3: nothing missing ==="
+set +e
+actual=$(CLIFF_CONTEXT=ctx.json bash "$ROOT/check-release-notes.sh" v0.1.0..HEAD 2> /dev/null)
+rc=$?
+set -e
+[ "$rc" -eq 0 ] || fail "expected exit 0, got $rc"
+[ -z "$actual" ] || fail "expected no output, got:
+$actual"
+echo "PASS"
+
+# Root commit: an empty %P field must not shift the subject into parents.
+new_repo "$TESTDIR/root"
+jq -n '[{commits: []}]' > ctx.json
+
+echo "=== Test 4: root commit keeps its subject ==="
+set +e
+actual=$(CLIFF_CONTEXT=ctx.json bash "$ROOT/check-release-notes.sh" HEAD 2> /dev/null)
+rc=$?
+set -e
+[ "$rc" -eq 1 ] || fail "expected exit 1, got $rc"
+expected="$(git rev-parse --short HEAD) chore: init"
+[ "$actual" = "$expected" ] || fail "unexpected output:
+$actual"
+echo "PASS"
+
+# The shared config is the contract for the guard's subject normalisation and
+# type list. Assert that the two have not drifted apart.
+echo "=== Test 5: guard constants match the shared cliff.toml ==="
+config="$ROOT/../../../cliff.toml"
+[ -f "$config" ] || fail "shared cliff.toml not found at $config"
+
+guard_emoji=$(awk -F"'" '/^EMOJI_RANGES=/{print $2}' "$ROOT/check-release-notes.sh")
+guard_types=$(awk -F"'" '/^CONVENTIONAL_TYPES=/{print $2}' "$ROOT/check-release-notes.sh")
+[ -n "$guard_emoji" ] || fail "could not read EMOJI_RANGES from check-release-notes.sh"
+[ -n "$guard_types" ] || fail "could not read CONVENTIONAL_TYPES from check-release-notes.sh"
+
+config_emoji=$(awk -F'[][]' '/1F000/{print $2}' "$config")
+[ "$config_emoji" = "$guard_emoji" ] || fail "EMOJI_RANGES drifted from the shared cliff.toml"
+
+config_types=$(grep -oE "message = '\^[a-z]+" "$config" | sed "s/message = '\^//" | sort -u | paste -sd'|')
+expected_types=$(printf '%s' "$guard_types" | tr '|' '\n' | sort -u | paste -sd'|')
+[ "$config_types" = "$expected_types" ] || fail "CONVENTIONAL_TYPES drifted from the shared cliff.toml (config: ${config_types})"
+echo "PASS"
+
+echo "✅ All tests passed"

.github/workflows/conventional-commits.yml

@@ -29,6 +29,50 @@ jobs:
             perf
             revert
           requireScope: false
+      - name: Breaking commits are marked in the PR title
+        if: github.event_name == 'pull_request'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+
+          # the PR commits endpoint returns at most 250, even with --paginate
+          count=$(jq '.pull_request.commits' "$GITHUB_EVENT_PATH")
+          if [ "$count" -gt 250 ]; then
+            echo "::error::This PR has $count commits, which exceeds the limit of 250 commits. Please squash your commits."
+            exit 1
+          fi
+
+          breaking_regex='^[a-z]+(\([^)]*\))?!:'
+
+          # Ignore merge commits: a merge from the base branch must not force
+          # this PR's title to be breaking. Only the subject's "!" counts,
+          # because the release config strips commit bodies before parsing.
+          breaking=$(gh api --paginate \
+            "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/commits" \
+            | jq -r --arg re "$breaking_regex" '
+                .[]
+                | select((.parents | length) < 2)
+                | (.commit.message | split("\n")[0]) as $subject
+                | select($subject | test($re))
+                | (.sha | .[0:7]) as $sha
+                | "\($sha) \($subject)"')
+
+          if [ -z "$breaking" ]; then
+            exit 0
+          fi
+
+          if [[ "$PR_TITLE" =~ $breaking_regex ]]; then
+            exit 0
+          fi
+
+          echo "::error::This PR contains breaking commit(s), but the PR title is not marked breaking."
+          printf '%s\n' "$breaking"
+          echo "Rename the PR title to a breaking conventional title, e.g. 'feat!:' or 'fix!:'."
+          echo "Editing the title reruns this check."
+          exit 1
 
   commitlint:
     name: Commit Messages