# /release — Release Workflow

Run this workflow when you're ready to cut a production release. Follow the steps in order.

---

## 1. Pre-flight Checks

Verify the repo is in a clean, releasable state:

```bash
# Must be on main and up to date
git checkout main && git pull

# Must be clean (no uncommitted changes)
git status

# Show recent commits since last tag (what's in this release)
git log $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD --oneline

Present the commit list to the user. If there are uncommitted changes, stop and ask the user to commit or stash them first.

Then verify the Neon production DB is at a known alembic revision (catches stale stamps before deploy):

# Load DATABASE_URL from .env.prod and check alembic state
# Must output: <revision-id> (head)
source .env.prod && DATABASE_URL=$DATABASE_URL backend/.venv/bin/alembic -c backend/alembic.ini current

If this fails with "Can't locate revision", follow the fix in CLAUDE.md → "When alembic_version has an unknown revision". Do not tag until this is resolved.

2. Run Full Test Suite

/Applications/Docker.app/Contents/Resources/bin/docker compose exec backend pytest tests/ -v --cov=src --cov-report=term-missing

Also run frontend tests:

cd frontend && npm run test:run && npm run build

Present results. If any tests fail, stop and ask the user what to do.

3. Security Review

Run the code review with a security focus:

/code-review uncommitted changes

Present any issues with confidence score ≥ 80. Ask the user:

"Security review complete. Any findings to fix before tagging?"

Wait for their response. Fix any flagged items, re-run tests, then continue.

4. Determine Version

Get the current latest tag:

git describe --tags --abbrev=0

Use the AskUserQuestion tool with a single question and three options. Compute the next PATCH/MINOR/MAJOR versions from the current tag and include them in the option labels. Example structure (replace vX.Y.Z with actual computed values):

Question: "What version should this release be? (current latest tag: vX.Y.Z)"
Header: "Version"
Options:
  - label: "vX.Y.Z+1 — PATCH"  description: "Bug fixes, no schema change"
  - label: "vX.Y+1.0 — MINOR"  description: "New features, may include a migration"
  - label: "vX+1.0.0 — MAJOR"  description: "Breaking API or schema changes"

Wait for their selection.

5. Bump `frontend/package.json`, Update STATUS.md, and Open a PR

main is protected — never push directly. Always use a PR.

Create a release branch, bump the version, update STATUS.md, and open a PR:

git checkout main && git pull
git checkout -b release/<VERSION>

# Check current value
node -e "const p = require('./frontend/package.json'); console.log('current:', p.version)"

Update frontend/package.json version to match the release tag (strip the leading v).

Also update STATUS.md — add a release entry at the top and update Last updated:. Both changes must be in the same commit.

# STATUS.md changes:
# - Update "Last updated:" line to today's date
# - Add a ## vX.Y.Z Release ✅ section at the top with the release tasks table

Then commit, push the branch, and open a PR:

git add frontend/package.json STATUS.md
git commit -m "chore: bump version to <VERSION>"
git push -u origin release/<VERSION>
gh pr create --title "chore: bump version to <VERSION>" --base main --head release/<VERSION> --body "..."

This commit is what gets tagged. The sidebar reads package.json at build time and STATUS.md reflects the release immediately — tagging alone does not update either.

6. Pre-Release Checklist

Run these checks on the release branch (before the PR is merged) to catch issues early.

# 1. Verify frontend/package.json version matches the release tag
node -e "const p = require('./frontend/package.json'); console.log(p.version)"

# 2. Verify no uncommitted changes remain on the release branch
git status

# 3. Check for any secrets accidentally staged (gitleaks-style quick check)
git log --oneline -5

# 4. Check if any Alembic migration files were added in commits since last tag
git diff $(git describe --tags --abbrev=0)..HEAD --name-only | grep alembic/versions || echo "No migrations in this release"

# 5. Verify RENDER_DEPLOY_HOOK_URL is set in GitHub Actions secrets
gh secret list | grep RENDER_DEPLOY_HOOK_URL || echo "WARNING: RENDER_DEPLOY_HOOK_URL not found"

Present verified results, then ask the user to confirm any items you could not auto-verify:

Pre-release checks:

[auto] frontend/package.json version: <verified value>

[auto] Working tree: clean /

[auto] Alembic migrations in this release: yes/no

[auto] RENDER_DEPLOY_HOOK_URL secret: present / NOT FOUND

All features for this release are merged to main — please confirm

7. Monitor PR CI and Notify

After opening the release PR, poll CI until it completes. Do not proceed to merge or ask release notes questions until CI is confirmed green.

# Get the run ID for the release branch CI
gh run list --repo noaraz/my-garmin-coach --branch release/<VERSION> --limit 3

# Watch until complete (exits when done)
gh run watch <run-id>

When CI completes:

Pass: notify the user: "CI passed on PR #. Ready to merge." Then present the full pre-release summary and wait for the user to confirm all items before asking them to merge.
Fail: show the failure summary (gh run view <run-id> --log-failed) and stop. Do not proceed until the user decides how to fix it.

After the user confirms and merges the PR, pull main:

git checkout main && git pull

8. Release Notes

Ask the user:

Write a short summary (1 line) and bullet-point release notes for this release. These will appear on the GitHub Release page.

Example:
Summary: First production release

- 