release

name	release
description	Use when the user asks to cut a release, bump the version, tag a new build, or publish release notes for quorum-desktop. Triggers on "release", "cut a release", "bump version", "new version", "tag a build", "release notes". Versioning only — this does NOT deploy to gh-pages (use the deploy skill for that).
allowed-tools	["Bash","Read","Edit","AskUserQuestion"]

Release Management

Version-bump, git-tag, and GitHub-release workflow for quorum-desktop.

This skill handles versioning only. It does not build or deploy. Shipping the build to app.quorummessenger.com stays with the separate deploy skill, and the prod-YYYY-MM-DD deploy tags stay with the prod-tag skill. A typical flow is: cut the release here, then run deploy to ship it.

Versioning scheme

This repo uses a base semantic version plus an incrementing build suffix:

2.1.0          first release (base, no suffix)
2.1.0-1        next build
2.1.0-2        next build
2.1.0-3        ...
2.1.1          "big change" — patch escalation, suffix resets
2.1.1-1        next build on the new base
2.2.0          minor escalation, suffix resets
3.0.0          major escalation, suffix resets

Default behaviour: increment the build suffix. This is what happens almost every release (2.1.0 → 2.1.0-1 → 2.1.0-2 → ...). Escalating the base version (to 2.1.1, 2.2.0, or 3.0.0) is rare and only happens when the user explicitly asks for it or confirms a "big change" — see Step 3. When in doubt, suffix-bump.

The version is stored only in package.json (the version field). Git tags mirror it with a v prefix: v2.1.0, v2.1.0-1, etc.

Version math (apply exactly)

Parse the current package.json version into BASE and optional SUFFIX: 2.1.0-3 → BASE=2.1.0, SUFFIX=3. 2.1.0 → BASE=2.1.0, SUFFIX=none.

• Suffix bump (default): keep BASE, set SUFFIX to (current SUFFIX or 0) + 1.
  • 2.1.0 → 2.1.0-1
  • 2.1.0-3 → 2.1.0-4
• Patch escalation (big change): major.minor.(patch+1), drop suffix.
  • 2.1.0-3 → 2.1.1
• Minor escalation: major.(minor+1).0, drop suffix.
  • 2.1.0-3 → 2.2.0
• Major escalation: (major+1).0.0, drop suffix.
  • 2.1.0-3 → 3.0.0

Special case — the very first release. If package.json is still at the placeholder 0.0.0 and no v* tags exist, the first release is 2.1.0 (the agreed starting point), not a computed bump. Set it directly.

Workflow

Step 1: Pre-flight

git rev-parse --abbrev-ref HEAD          # must be main
git status --porcelain                   # must be clean
git tag -l "v*" --sort=-version:refname | head -10
node -e "console.log(require('./package.json').version)"

• If the branch is not main → STOP, tell the user. (Releases are cut from main.)
• If there are uncommitted changes → STOP, tell the user to commit or stash first.
• Note the current version and the latest v* tag.

Step 2: Analyze commits since the last release

Find the reference point: the latest v* tag, or if none exist, the latest prod-* tag, or the root commit.

git log <LATEST_VERSION_TAG>..HEAD --format="%h%x09%s"

• If there are no new commits since the last v* tag → "Nothing to release." and stop.
• Categorize each commit by conventional-commit prefix:
  • feat: / feat(...) → Features
  • fix: → Bug Fixes
  • doc: / docs: → Documentation
  • chore:, refactor:, style:, test:, build:, ci:, perf: → Maintenance
  • feat!:, fix!:, or a body containing BREAKING CHANGE → Breaking
  • anything else → Other
• A commit is a "big change" signal if it is a feat:, any ! breaking marker, or contains BREAKING CHANGE.

Step 3: Decide the new version

Compute the default new version = a suffix bump (per the version math above).

Then decide whether to escalate:

• First release ever (placeholder 0.0.0, no v* tags): the new version is 2.1.0. Skip the escalation question — confirm 2.1.0 and proceed.
• Big-change signal present (any feat / breaking commit since last release): use AskUserQuestion to ask the user how to version this release. Offer:
  • "Build suffix — <default suffix version>" (Recommended if changes are small/iterative)
  • "Patch — <patch escalation>" (a meaningful but compatible change)
  • "Minor — <minor escalation>" (a notable feature set)
  • "Major — <major escalation>" (a breaking or landmark release) Show the actual computed numbers in each label.
• No big-change signal: default to the suffix bump silently, but still state the chosen version in Step 5 so the user can object before the push gate.

Never escalate without an explicit user choice. The default is always the suffix bump.

Step 4: Bump package.json

Edit the version field in package.json to the chosen new version. Change only that field. Do not touch any other file (no version.ts, no CHANGELOG.md — release notes live on the GitHub release).

Step 5: Commit & tag

Report to the user first:

• Previous version → New version (bump kind: suffix / patch / minor / major / initial)
• Number of commits included
• A one-line summary of the categorized changes

Then:

git add package.json
git commit -m "chore(release): v<NEW_VERSION>"
git tag -a v<NEW_VERSION> -m "v<NEW_VERSION>"

• If the tag v<NEW_VERSION> already exists → STOP and report. (Should not happen with correct math, but guard anyway.)

Step 6: Push & GitHub release

Use AskUserQuestion:

• "Push release to remote and create the GitHub release?"
• Options: "Yes, push and release" (Recommended) / "No, I'll do it later"

If no: stop here. Tell the user the commit and tag exist locally and how to push them later (git push origin main --tags).

If yes:

git push origin main --tags

Then create the GitHub release on QuilibriumNetwork/quorum-desktop with grouped changelog notes:

gh release create "v<NEW_VERSION>" --title "v<NEW_VERSION>" --notes "<changelog>"

For a build-suffix release (e.g. v2.1.0-2), mark it as a pre-release so it does not show as the "Latest" release above the base version:

gh release create "v<NEW_VERSION>" --title "v<NEW_VERSION>" --prerelease --notes "<changelog>"

(Base versions like v2.1.0, v2.1.1, v2.2.0 are full releases — no --prerelease.)

Step 7: Report

Display:

• Previous version → new version
• Commit hash and tag name
• GitHub release URL (if created)
• A reminder: "To ship this build live, run the deploy skill."

Release notes format

Generate notes with only the sections that have changes, in this order:

## Breaking Changes
- Description (short-hash)

## Features
- Description (short-hash)

## Bug Fixes
- Description (short-hash)

## Documentation
- Description (short-hash)

## Maintenance
- Description (short-hash)

• Write each line from the user's perspective — what changed for them, not the raw commit subject. Drop the conventional-commit prefix.
• Keep the (short-hash) at the end of each line for traceability.
• Use standard punctuation, not em dashes.
• Never mention Claude, AI, Anthropic, or any tooling in release notes, commit messages, or tags.

Edge cases

• No new commits since last v* tag → "Nothing to release." Stop.
• Uncommitted changes → STOP, ask the user to commit or stash first.
• Not on main → STOP, releases are cut from main.
• Tag already exists → STOP and report; do not overwrite.
• gh CLI unavailable or not authenticated → the git push still succeeds; tell the user the tag is pushed and they can create the GitHub release manually at the repo's Releases page.
• First release → version is 2.1.0, set directly (no computed bump).

Files modified

• package.json — the version field only.
• Git commit: chore(release): vX.Y.Z[-N]
• Git tag: vX.Y.Z[-N] (annotated)
• GitHub release with grouped changelog notes (pre-release for suffix builds)

---

Last updated: 2026-06-12