Patch Release Scenarios

All Patch Release scenarios automatically bump the patch version (e.g. 2.1.31 → 2.1.32). PR titles do not need to include a version number.

1. Weekly Release (canary → main)

The most common release type. Collects a week's worth of changes from canary and ships them to main.

Steps

1. Create release branch from canary

git checkout canary
git pull origin canary
git checkout -b release/weekly-{YYYYMMDD}
git push -u origin release/weekly-{YYYYMMDD}

2. Scan changes and write changelog

Compute the previous tag from main first — never reuse the last weekly's tag, since hotfixes published in between will be missed:

git fetch origin main canary --tags
PREV_TAG=$(git describe --tags --abbrev=0 origin/main --match 'v*.*.*' --exclude '*-canary*' --exclude '*-nightly*')
git log "$PREV_TAG..origin/release/weekly-{YYYYMMDD}" --oneline --no-merges
git diff "$PREV_TAG...origin/release/weekly-{YYYYMMDD}" --stat

Then follow ./release-notes-style.md § Computing Inputs (Hard Rules) to derive PR refs, metrics, and contributors. Every (#XXXX) in the body must come from actual commit subjects in this range — never inferred from descriptions.

3. Create PR to main with the changelog as the PR body

gh pr create \
  --title "🚀 release: {YYYYMMDD}" \
  --base main \
  --head release/weekly-{YYYYMMDD} \
  --body-file changelog.md

4. After merge: auto-tag-release detects release/* branch → auto patch +1.

2. Bug Hotfix

Emergency bug fix shipped directly from main.

Steps

1. Create hotfix branch from main

git checkout main
git pull --rebase origin main
git checkout -b hotfix/v{version}-{short-hash}
git push -u origin hotfix/v{version}-{short-hash}

2. Create PR to main with a gitmoji prefix title (e.g. 🐛 fix: description)

3. Write a short hotfix changelog — See changelog-example/hotfix.md. Keep it minimal: scope line, 1-3 fix bullets (symptom + fix in one sentence), upgrade note, owner. No long root-cause section — that lives in the commit message.

   • Hotfix owner: Use the actual PR author (retrieve via gh pr view <number> --json author --jq '.author.login'), never hardcode a username.

4. After merge: auto-tag-release detects hotfix/* branch → auto patch +1.

Script

bun run hotfix:branch

3. New Model Launch

New AI model or provider support, typically contributed via community PRs.

How it works

• Community contributors submit PRs with titles like ✨ feat: add xxx model or 💄 style: support xxx models
• These PR title prefixes (feat / style) are in the auto-tag trigger list
• No special branch naming or manual release steps required — merging the PR triggers auto patch +1

When Claude is involved

If asked to add model support, just create a normal feature PR. The title prefix will trigger the release automatically.

4. DB Schema Migration

Database schema changes that need to be released independently. These require a dedicated changelog explaining the migration for self-hosted users.

Steps

1. Create release branch from main and cherry-pick migration commits

git checkout main
git pull --rebase origin main
git checkout -b release/db-migration-{name}
git cherry-pick <migration-commit-hash>
git push -u origin release/db-migration-{name}

2. Write a migration-specific changelog — See db-migration-changelog-example.md for the format. This should explain:

   • What tables/columns are added, modified, or removed
   • Whether the migration is backwards-compatible
   • Any action required by self-hosted users
   • Migration owner: Use the actual PR author (retrieve via gh pr view <number> --json author --jq '.author.login' or git log commit author), never hardcode a username

3. Create PR to main with the migration changelog as the PR body

gh pr create \
  --title "👷 build: {migration description}" \
  --base main \
  --head release/db-migration-{name} \
  --body-file changelog.md

4. After merge: auto-tag-release detects release/* branch → auto patch +1.