/release

name: release
description: >-
  Cut a software release and maintain a tiered compatibility policy. Use when the
  user wants to release, ship a version, bump the version, tag a release, write a
  changelog, or update COMPATIBILITY. Config-driven via release.config.json;
  bumps version files, runs a readiness gate, updates COMPATIBILITY.md tiers and
  deprecations, tags (→ release workflow), and reports closed issues. Teaches the
  underlying standards as it runs.

release — tiered compatibility & release workflow

For the Cull repository, use `$cull-release`; Cull's repository-enforced state, artifact, updater, and Homebrew gates are stricter than this generic workflow.

A config-driven release orchestrator. Mechanics live in `scripts/release.py` (unit-tested, stdlib-only); this file is the workflow you (or an agent) follow. Read `reference/config-schema.md` for `release.config.json` and `reference/standards.md` for *why* each step exists.

> **Scope honesty:** reference-tested on a Tauri + Rust + SvelteKit repo (Cull). > Other stacks are supported *by config*, not yet validated. Treat first runs on > a new stack as a dry run (see "Dry run" below) until you trust it.

When to use

The user says "release", "ship it", "cut a version", "bump version", "tag a release", "update the changelog/COMPATIBILITY". Requires a `release.config.json` at the repo root (scaffold from `templates/release.config.json.tmpl`).

Mental model — your public API is your declared surfaces

A version only means something once you declare *what you promise to keep working*. `release.config.json → surfaces[]` is that declaration; each surface has a **tier** (`experimental → preview → stable`) and a compatibility **mode**. Only `stable` surfaces carry the promise. Breaking a `stable` surface forces a **major** bump — the engine enforces this. (Standards: see `reference/standards.md`.)

Command

`/release <patch|minor|major>` — run the steps below. On an unfamiliar repo, do a **dry run first** (see below). When the user asks to "explain", expand each step's *why* into a short lesson from `reference/standards.md`.

Steps

1. **Preconditions.** The configured `releaseBranch` (default `main`, in `worktree` if set) is checked out, clean, and synced with `origin`. Abort clearly otherwise. — *why: a release tag must point at a known-good, pushed tree.*

2. **Version.** `python3 scripts/release.py --config <cfg> plan <kind>` prints the new version + tag. It asserts the version files currently agree. Show `old → new`. — *why: SemVer math; 0.x lets minors break (pre-1.0).* [[Semantic Versioning (SemVer)]]

3. **Readiness gate.** Run `cfg.gate` then each `cfg.extraGate[]`. All must exit 0 (fmt, clippy, tests, license audit, prod build, golden contract tests). Block on failure. — *why: this is a Production-Readiness Review.* [[Production Readiness Review]]

• TODO (deferred): cargo-deny / cargo-audit / SBOM. List, don't enforce yet.

4. **Changelog.** Collect commit subjects since the last tag (`git log <lastTag>..HEAD --format=%s`) and draft a section — the engine's `draft_changelog` buckets them into Added/Changed/Fixed (Keep a Changelog). Insert under the top of `CHANGELOG.md`; **hand-curate** the user-facing lines. — *why: humans read changelogs; conventional commits seed them.* [[Keep a Changelog]]

5. **Compatibility review.** Open `cfg.compatibility.path` (COMPATIBILITY.md). Ask:

• Did any surface change tier? (update the Surfaces table)
• New deprecations? (add a row: item / deprecated-in / removable-in / replacement)
• **Does this change break a `stable` surface?** If yes, the required bump is

`major` — re-run with `major` or the release is invalid. (Enforced by `enforce_bump`.) Stamp "Last updated: <new version> (<date>)". — *why: tiers + deprecation windows are how you evolve without lying.* [[Kubernetes API Deprecation Policy]]

6. **Bump & commit.** `python3 scripts/release.py --config <cfg> bump <kind>` writes every version file; refresh `cfg.lockfiles` (e.g. `cargo update -p <crate>` or a build). Commit `chore(release): v<new>` including CHANGELOG + COMPATIBILITY.

7. **Tag & push.** `git tag v<new>` and push the tag (→ the repo's release workflow) and the branch. Confirm the tag trigger exists *before the first release* (`grep -A3 '^on:' .github/workflows/*.yml`).

8. **Report.** Print the tag, the release-workflow URL, and issues closed since the last tag (if `cfg.issueTracker` is set, e.g. bd) — those are the release notes.

Dry run

There is no `--dry-run` flag — a dry run is steps 1–5 done *without mutating*: run `python3 scripts/release.py --config <cfg> plan <kind>` (pure: prints the version/tag, writes nothing) and optionally run `cfg.gate` to check readiness. Do NOT run `bump`, commit, or tag. The `bump` subcommand is the only engine command that writes (version files only); commit/tag/push are git steps you take in step 6–7, never the engine.

Manual fallback (no skill)

`plan` → run gate → edit CHANGELOG + COMPATIBILITY → `bump` → commit → tag → push. The engine is just `scripts/release.py`; everything else is git.

Growing into Contracts & Modes

The readiness gate runs *golden/contract tests* (`cfg.extraGate`). Start with one (a DB round-trip), then add export and API contract tests. See the consuming repo's `docs/CONTRACTS.md` and `reference/standards.md`. [[Pact — Consumer-Driven Contract Testing]]