Automate release checklist for version and changelog

Author: mgomes

.github/workflows/release-checklist.yml

@@ -0,0 +1,24 @@
+name: release-checklist
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (vMAJOR.MINOR.PATCH)"
+        required: true
+        type: string
+
+jobs:
+  checklist:
+    runs-on: ubuntu-latest
+    env:
+      RELEASE_VERSION: ${{ github.event_name == 'workflow_dispatch' && inputs.version || github.ref_name }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate release checklist
+        run: ./scripts/release_checklist.sh "${RELEASE_VERSION}"

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+- Ongoing work toward `v0.19.0` tooling and quality milestones.
+
+## v0.19.0 - Unreleased
+
+- Milestone in progress. Use this section for release-ready change summaries.
+
+## v0.1.0 - 2026-02-19
+
+- Initial pre-1.0 project baseline and public documentation set.

ROADMAP.md

@@ -334,7 +334,7 @@ Goal: improve day-to-day developer productivity and interpreter robustness.
 ### CI and Release Engineering
 
 - [x] Add smoke tests for docs examples to CI.
-- [ ] Add release checklist automation for changelog/version bumps.
+- [x] Add release checklist automation for changelog/version bumps.
 - [x] Add compatibility matrix notes for supported Go versions.
 
 ### v0.19.0 Definition of Done

cmd/vibes/repl.go

@@ -558,7 +558,7 @@ func (m replModel) View() string {
 	var b strings.Builder
 
 	header := headerStyle.Render("VibeScript REPL")
-	version := mutedStyle.Render("v0.1.0")
+	version := mutedStyle.Render("v0.19.0")
 	b.WriteString(header + " " + version + "\n")
 	b.WriteString(mutedStyle.Render(strings.Repeat("─", min(m.width-2, 60))) + "\n\n")
 

docs/releasing.md

@@ -14,6 +14,25 @@ This repository uses GoReleaser for changelog generation and GitHub releases. Th
 1. Tag the release locally and push it (e.g., `git tag -a v0.1.0 -m "v0.1.0"` then `git push origin v0.1.0`).
 2. GitHub Actions picks up `v*` tags via `.github/workflows/release.yml` and runs `goreleaser release --clean` with `GITHUB_TOKEN` injected.
 
+## Automated release checklist
+
+Before tagging, run the checklist automation:
+
+```bash
+./scripts/release_checklist.sh v0.1.0
+```
+
+The checklist verifies:
+
+- `CHANGELOG.md` contains a `## vX.Y.Z` heading.
+- `ROADMAP.md` contains a matching milestone heading.
+- The REPL version label in `cmd/vibes/repl.go` matches the target version.
+- The version tag does not already exist locally.
+
+The same validation runs automatically on tag pushes via
+`.github/workflows/release-checklist.yml` and can also be run manually via
+GitHub Actions `workflow_dispatch`.
+
 ### Local dry run (optional)
 
 If you want to test locally instead of waiting for CI:

scripts/release_checklist.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+  echo "usage: scripts/release_checklist.sh <version>" >&2
+  echo "example: scripts/release_checklist.sh v0.19.0" >&2
+  exit 2
+fi
+
+version="$1"
+if [[ ! "${version}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+  echo "invalid version '${version}': expected vMAJOR.MINOR.PATCH" >&2
+  exit 2
+fi
+
+fail() {
+  echo "release checklist failed: $1" >&2
+  exit 1
+}
+
+[[ -f CHANGELOG.md ]] || fail "missing CHANGELOG.md"
+[[ -f ROADMAP.md ]] || fail "missing ROADMAP.md"
+[[ -f cmd/vibes/repl.go ]] || fail "missing cmd/vibes/repl.go"
+
+grep -Eq "^## ${version}( |$)" CHANGELOG.md || fail "CHANGELOG.md missing heading for ${version}"
+grep -Eq "^## ${version}( |$)" ROADMAP.md || fail "ROADMAP.md missing milestone heading for ${version}"
+grep -Fq "version := mutedStyle.Render(\"${version}\")" cmd/vibes/repl.go || fail "REPL version label does not match ${version}"
+
+if git rev-parse -q --verify "refs/tags/${version}" >/dev/null 2>&1; then
+  fail "git tag ${version} already exists locally"
+fi
+
+echo "release checklist passed for ${version}"