App Release

Release

Overview

Release is done by pushing a v* tag. CI validates the release metadata, builds all platforms, creates a GitHub Release, and then updates the website version and Homebrew cask. Manual steps: update the changelog and version files, commit them together, then tag and push. The workflow is asynchronous: after a successful tag push, report that the release was triggered; do not wait for CI unless the user explicitly asks.

Announce at start: "I'm using the release skill to ship a new version."

When to Use

digraph when_release {
    "User asks to release/ship/publish?" [shape=diamond];
    "Use this skill" [shape=box];
    "Homebrew 404 or artifact-not-found after a tag push?" [shape=diamond];
    "Use this skill" [shape=box];
    "Pre-release checks (code review, QA)?" [shape=diamond];
    "Not this skill — use requesting-code-review" [shape=box];

    "User asks to release/ship/publish?" -> "Use this skill" [label="yes"];
    "User asks to release/ship/publish?" -> "Homebrew 404 or artifact-not-found after a tag push?" [label="no"];
    "Homebrew 404 or artifact-not-found after a tag push?" -> "Use this skill" [label="yes"];
    "Homebrew 404 or artifact-not-found after a tag push?" -> "Pre-release checks (code review, QA)?" [label="no"];
    "Pre-release checks (code review, QA)?" -> "Not this skill — use requesting-code-review" [label="yes"];
}

Use when:

• User says "release", "ship", "publish", "new version", "bump version"
• Homebrew cask update failed (404 on DMG URLs)
• CI create-release job failed to find artifacts

Don't use for:

• Code review before releasing
• Deciding WHAT version number (ask the user)
• Feature work or bug fixes

Quick Reference

Core Pattern

All file changes (CHANGELOG, Cargo.toml, Cargo.lock, package.json) are made and committed together in a single commit. Do not commit after each step. (docs/version.json is updated by CI post-release.)

1. Confirm Version

Ask the user. Check git tag --sort=-v:refname | head -5 for context. Version must start with v (only v* tags trigger CI).

2. Update CHANGELOG.md

Add a new version section before the previous release entry:

## [X.Y.Z] — YYYY-MM-DD

Use today's date. Group changes under Added, Changed, Fixed headings. Review commits since the last tag with git log --oneline v<LAST>..HEAD to ensure nothing is missed.

Do NOT commit yet — all changes go into one commit in Step 5.

3. Protocol Impact Check

After writing the changelog, decide whether this release changes the desktop-owned local protocol. Desktop is the source of truth for local state; the CLI is an adjunct control surface and must follow the desktop protocol.

Use changed paths as review prompts, not automatic gates. Relevant prompts include desktop persistence structs, archive/restore behavior, local state paths or shapes, schema versions, and CLI protocol read/write code. Trigger the protocol gate only when the release changes desktop-owned local state shape, paths, schema versions, lock/archive write semantics, or user-visible compatibility/migration behavior.

If there is no protocol impact, note it internally and continue. Do not add "no impact" lines to CHANGELOG or commit messages.

If there is protocol impact, verify before continuing:

1. AGENTS.md guidance still reflects the desktop-owned protocol relationship.
2. docs/local-protocol.md reflects the current desktop protocol.
3. fixtures/local-protocol/ represents the desktop protocol, not CLI implementation convenience.
4. CLI and Rust protocol fixture tests pass.
5. CHANGELOG mentions any user-visible compatibility, migration, or breaking behavior.

4. Update Version Files

Update src-tauri/Cargo.toml and package.json with apply_patch so the instructions work consistently on macOS, Linux, and Windows agents. Both files use bare semver without the v prefix. Then regenerate Cargo.lock:

cargo check --manifest-path src-tauri/Cargo.toml

Do NOT update docs/version.json here — CI updates it automatically after the release is published.

Do NOT commit yet — all changes go into one commit in Step 5.

5. Verify Prerequisites

Run all checks in order. If any fails, fix and re-run the full sequence until clean — formatting changes can cascade into lint results. Any fixes become part of the same release commit.

1. cargo fmt --check --manifest-path src-tauri/Cargo.toml — run cargo fmt --manifest-path src-tauri/Cargo.toml if diffs appear, then restart from here
2. bun run lint:rs — fix all warnings; fmt may have introduced new ones
3. cargo test --manifest-path src-tauri/Cargo.toml --features test-helpers — fix any test failures before proceeding
4. bun run typecheck — fix all type errors before proceeding
5. bun run lint — fix any lint errors. Note: pre-existing issues unrelated to this release should be noted separately, not silently fixed in the release commit
6. bun run format:check — run bun run format if diffs appear. CI also enforces this, but catching it locally avoids a broken tag
7. RELEASE_BODY.md uses __VERSION__ and __COMMITS__ placeholders — never hardcoded version numbers
8. git status --short — only expected files (CHANGELOG.md, Cargo.toml, Cargo.lock, package.json, plus any fmt/clippy fixes) should appear. docs/version.json should NOT appear (CI updates it post-release). Anything else is a stray change that could slip into the release commit.

When all checks pass, commit everything in a single commit:

git add CHANGELOG.md src-tauri/Cargo.toml src-tauri/Cargo.lock package.json
# also add any files modified by fmt/clippy fixes above
git commit -m "chore: release vX.Y.Z"

6. Tag and Push

CRITICAL: Pushing a v* tag triggers CI to build and publish a release. Always tell the user explicitly that a push is about to happen and get their consent before executing. Never push without approval.

Note: git push triggers .githooks/pre-push, which re-runs the full check suite and takes minutes — this is the intentional local gate that keeps a broken push from reaching CI. Run the push in the background or with a generous timeout; a foreground push can be killed mid-hook by the default command timeout, leaving main unpushed and no tag.

git push origin main
git tag v0.1.2
git push origin v0.1.2

Once the tag push succeeds, the release has been triggered. Report the pushed tag and commit, and stop without polling GitHub Actions unless the user asked to wait or monitor the release.

7. CI Jobs (triggered by v* tag)

docs/version.json is updated by CI after create-release succeeds — never manually. This ensures the download website only points to published artifacts.

Common Mistakes