release - SKILL.md Agent Skill

name: release description: Release char macOS app. Bumps version, updates changelog, creates git tag, monitors CI, verifies release assets, and updates Homebrew tap. Use when releasing a new version.

char Release Process

Follow these steps to ship a new macOS release for char.

Pre-flight Checks

Before starting:

Verify you're on the main branch
Ensure working tree is clean (no uncommitted changes)
Pull latest changes: git pull origin main

git status
git branch --show-current

Step 1: Bump Version

Update versions in char.xcodeproj/project.pbxproj:

MARKETING_VERSION - Bump the patch version (e.g. 1.0.9 -> 1.0.10).
CURRENT_PROJECT_VERSION - Increment the integer by 1

Use the Edit tool to update both occurrences of each version field.

Commit the version bump:

git add char.xcodeproj/project.pbxproj
git commit -m "chore: bump version to X.Y.Z"

Step 2: Update Changelog

Check commits since the last tag:

git log $(git describe --tags --abbrev=0)..HEAD --oneline

Add release notes to CHANGELOG.md under a new version heading. Only include meaningful changes (features, fixes, docs). Skip version-bump-only entries.

Commit the changelog:

git add CHANGELOG.md
git commit -m "docs: update changelog for X.Y.Z"

Step 3: Create and Push Tag

Create a git tag and push it to trigger the Release workflow:

git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z

Step 4: Monitor CI

Watch the Release workflow:

gh run list --workflow Release --limit 1
gh run watch

If no run shows up yet, wait a moment and retry until it appears:

sleep 10
gh run list --workflow Release --limit 1

If the workflow fails, inspect logs:

gh run view --log-failed

Step 5: Verify Release Assets

Confirm the release has the required assets:

gh release view vX.Y.Z --json url,assets

Required assets:

char.dmg
appcast.xml

Step 6: Update Homebrew Tap

Download the DMG and compute SHA256:

gh release download vX.Y.Z --pattern "*.dmg" --dir /tmp
shasum -a 256 /tmp/char.dmg

Update 851-labs/homebrew-tap repository:
- Edit Casks/char.rb
- Set version "X.Y.Z"
- Set sha256 "<computed-hash>"
Commit and push the tap update

Validate the install:

brew update
brew upgrade --cask 851-labs/tap/char

Troubleshooting

Notarization Delays

Notarization can take 10-45 minutes depending on Apple queue load. The CI logs show submission IDs.

Query notarization status (requires API credentials):

xcrun notarytool info <submission-id> \
  --key <AuthKey.p8> \
  --key-id <KEY_ID> \
  --issuer <ISSUER_ID> \
  --output-format json

Sparkle Feed

The appcast URL for automatic updates:

https://github.com/851-labs/char/releases/latest/download/appcast.xml