Release

---
name: release
description: Git release workflow for creating patches and releases with proper versioning
---

# Release Workflow Skill

This skill guides you through the proper release workflow for this project, ensuring all versioning artifacts stay in sync.

## Arguments

- `$1` - Version bump type: `patch` (default), `minor`, or `major`
- `--github-release` - Also create a GitHub Release (triggers upgrade notice in app). **Automatically applied for `minor` and `major` bumps — do not omit it.**
- `--docs-only` - Skip version changes (for documentation-only PRs)

## Rules

- **Every `minor` or `major` bump MUST create a GitHub Release.** Do not run `npm run release:minor` or `npm run release:major` without `--github-release`. This is not optional — GitHub Releases trigger the upgrade notice banner.
- **`patch` bumps do NOT create a GitHub Release** unless explicitly requested.

## Workflow Overview

The release workflow depends on the current git state:

### Scenario A: Changes on a Feature Branch (Pre-PR)

If on a feature branch with uncommitted or committed changes:

1. **Update CHANGELOG.md** with the next version and changes
2. **Update package.json** with the next version (required for Vercel)
3. **Commit** the version changes
4. **Push** and create PR
5. **Watch CI**: `gh pr checks <pr> --watch` — wait until all checks pass
6. **Check Copilot inline comments**: `gh api repos/<owner>/<repo>/pulls/<pr>/comments` — address any actionable ones, push, re-run CI if needed
7. **Resolve review threads**: get unresolved thread IDs via GraphQL, resolve each one
8. **Merge**: `gh pr merge <pr> --squash --delete-branch --admin`
9. **Tag**: `npm run release:patch -- -y --push --sync-package` (on main after merge)

### Scenario B: On Main Branch After Merge (Tag Creation)

If on main branch with no uncommitted changes:

1. **Update `docs/ROADMAP.md`** — set "Now" to the new version + one-line summary, move shipped features from Next/Backlog to Shipped table. If changes needed, create a docs-only PR (`git commit --no-verify -m "docs: update ROADMAP for vX.Y.Z"`) and merge it before tagging
2. **Verify** package.json matches the version to tag
3. If not, create a quick PR to sync package.json
4. **Create git tag** pointing to current HEAD
5. **Push tag** to origin
6. Optionally **create GitHub Release** (if `--github-release` specified)

### Scenario C: Docs-Only Changes (No Version Needed)

If `--docs-only` is specified:

1. Skip all version-related steps
2. Just commit and create PR
3. CI will skip build for docs-only changes

## Step-by-Step Instructions

### Step 1: Determine Current State

```bash
# Check current branch
git rev-parse --abbrev-ref HEAD

# Check for uncommitted changes
git status --porcelain

# Get latest tag
git tag -l v* --sort=-version:refname | head -1

# Get package.json version
grep '"version"' package.json

Step 2: Calculate Next Version

Based on the bump type ($ARGUMENTS or default to patch):

• patch: 0.82.5 → 0.82.6
• minor: 0.82.5 → 0.83.0 ← GitHub Release is mandatory
• major: 0.82.5 → 1.0.0 ← GitHub Release is mandatory

Step 3: Pre-PR Checklist (if on feature branch)

Before creating the PR, ensure:

1. CHANGELOG.md updated with new version section
2. package.json version updated to match
3. docs/ROADMAP.md updated — "Now" section reflects current version, shipped features moved to Shipped table, Next section reflects actual upcoming work
4. Changes committed with conventional commit message
5. Branch pushed to origin

Step 4: Watch, Merge, and Tag (continuation of Scenario A)

After creating the PR, continue autonomously — do NOT stop and ask the user to run /release again:

# 4a. Watch CI — blocks until all checks pass or fail
gh pr checks <pr-number> --watch

# 4b. Check Copilot inline comments — address any actionable ones before merging
#     These are separate from review threads and won't show up in PR checks
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
gh api repos/${REPO}/pulls/<pr-number>/comments | jq '.[].body'
# If any actionable comments exist: fix, push, re-run from 4a
# If none (or only resolved): proceed

# 4c. Resolve all unresolved review threads (required by branch ruleset)
gh api graphql -f query="{
  repository(owner: \"${REPO%/*}\", name: \"${REPO#*/}\") {
    pullRequest(number: <pr-number>) {
      reviewThreads(first: 100) {
        nodes { id isResolved }
      }
    }
  }
}" --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | .id' \
  | while read id; do
      gh api graphql -f query="mutation { resolveReviewThread(input: { threadId: \"$id\" }) { thread { isResolved } } }"
    done

# 4d. Merge — try standard merge first; use --admin only if branch protection blocks it
gh pr merge <pr-number> --squash --delete-branch \
  --subject "<same title as PR>" \
  || gh pr merge <pr-number> --squash --delete-branch --admin \
       --subject "<same title as PR>"

# 4e. Switch to main and tag
git checkout main && git pull

# For patch:
npm run release:patch -- -y --push --sync-package

# For minor (GitHub Release is MANDATORY):
npm run release:minor -- -y --push --sync-package --github-release

# For major (GitHub Release is MANDATORY):
npm run release:major -- -y --push --sync-package --github-release

If any CI check fails: fix the issue, push a new commit, re-run step 4a.

If Copilot inline comments are actionable: fix the code, push, re-run from step 4a. Non-actionable comments (style suggestions, questions) can be resolved without code changes.

If review threads have actionable comments: same — address with code changes, push, re-run from step 4a.

Step 5: Verify Release

After release:

1. Check GitHub for new tag: gh browse --repo $(gh repo view --json nameWithOwner -q .nameWithOwner) releases
2. Verify Vercel deployment triggered
3. If GitHub Release created, check upgrade notice in app