renatocaliari/skills/local/cali-releases

Releases

Rule: Any merge/push to main MUST include a GitHub release. Do not wait to be asked — generate release automatically.

Read first: {project}/.pi/instructions.md (if exists)

Contents

| Section | What | When to consult | |---------|------|------------------| | Versioning Rules | Alpha/beta convention, version increments | Before creating any release | | Release Flow | 5-step process from checks to verification | On every merge to main | | Emergency Hotfix | Critical fix release process | When production is broken | | CI/CD Integration | ko build trigger on release | When project uses ko | | References | ko build pipeline details | When configuring builds |

Versioning Rules

| Rule | Example | |------|---------| | Use alpha/beta only | 0.2.0-alpha, 0.3.1-beta | | NEVER 1.0.0 without owner confirmation | ❌ 1.0.0 → ✅ 0.9.0 | | Increment patch for fixes | 0.2.0 → 0.2.1 | | Increment minor for features | 0.2.0 → 0.3.0 | | Increment major for breaking | 0.2.0 → 1.0.0 (with approval) |

Release Flow

1. Pre-release Checks

# Run tests
npm run test        # or: go test ./... / make test

# Run linter
npm run lint        # or: golangci-lint run

# Check for uncommitted changes
git status

2. Determine Version

# Check current version
git tag --sort=-v:refname | head -5

# Or check package.json / go module version

3. Create Release

# Create release (interactive — pick or type version)
gh release create

# Or explicit:
gh release create v0.X.Y-alpha \
  --title "v0.X.Y-alpha: <summary>" \
  --notes "## Changes

- Feature: description
- Fix: description

## Breaking Changes

- None (or list)

## Testing

- [ ] All tests pass
- [ ] Manual verification done"

4. Push Tag (if not auto-pushed)

git push origin v0.X.Y-alpha

5. Verify

# Check release appears
gh release list

# Check tag exists
git tag -l "v0.X.Y*"

Release Notes Template

## v0.X.Y-alpha

### What's Changed
- Feature: description (#PR)
- Fix: description (#PR)

### Breaking Changes
- None (or list)

### Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual smoke test done

Emergency Hotfix Release

# 1. Create hotfix branch
git checkout -b hotfix/fix-critical main

# 2. Make fix, commit
git commit -m "fix: critical issue description"

# 3. Merge to main
git checkout main
git merge hotfix/fix-critical

# 4. Create release immediately
gh release create v0.X.Y-alpha \
  --title "v0.X.Y-alpha: Hotfix - description" \
  --notes "Critical fix for..."

# 5. Clean up
git branch -d hotfix/fix-critical

CI/CD Integration

If project uses ko for builds, the release can trigger image builds:

# .github/workflows/deploy.yml (triggered on release)
on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ko-build/[email protected]
      - run: ko build --platform=linux/amd64,linux/arm64 --bare ./cmd/web/

Examples

Example 1: Standard release after feature merge

Input: "Just merged the auth feature to main"

Steps:

1. Run: git tag --sort=-v:refname | head -3 → last tag was v0.2.0-alpha
2. Run: gh release create v0.3.0-alpha --title "v0.3.0-alpha: Auth feature" --notes "..."
3. Run: git push origin v0.3.0-alpha

Output: "Released v0.3.0-alpha with auth feature. Tag pushed."

Example 2: Emergency hotfix

Input: "Production is down, critical bug in auth"

Steps:

1. Run: git checkout -b hotfix/fix-auth-crash main
2. Make fix, commit
3. Merge to main
4. Run: gh release create v0.2.1-alpha --title "v0.2.1-alpha: Hotfix auth crash" --notes "..."

Output: "Hotfix released v0.2.1-alpha. Production should recover."

Example 3: Version decision

Input: "What version should I use for this release?"

Steps:

1. Check: git tag --sort=-v:refname | head -5
2. Check: what changed since last tag? git log v0.2.0-alpha..HEAD --oneline
3. If breaking: 0.3.0-alpha. If feature: 0.2.1-alpha. If fix: 0.2.0.1-alpha

Output: "Based on 3 feature commits since v0.2.0-alpha, recommend v0.3.0-alpha."

Edge Cases

Tests fail before release

• BLOCK the release. Do not create.
• Tell user: "Tests failing — fix first, then release"
• Offer to run tests: go test ./... or npm test

No changes since last release

• Check: git diff v0.X.Y-alpha..HEAD --stat
• If empty: "No changes since last release. Nothing to release."
• Don't create empty releases

gh CLI not authenticated

• Check: gh auth status
• If not logged in: gh auth login (interactive)
• Tell user they need to authenticate first

Tag already exists

• Check: git tag -l "v0.X.Y*"
• If tag exists: "Tag v0.X.Y-alpha already exists. Use v0.X.Y.1-alpha or delete the tag first."

Test Cases

Should activate

• "Create a release"
• "Push a release to main"
• "We merged to main, release now"
• "What version should this be?"
• "Emergency hotfix needed"

Should NOT activate

• "Write release notes" (just writing, not releasing)
• "What's the current version?" (just asking, not releasing)
• "Run the tests" (testing, not releasing)

References

• references/ko-build.md — ko build pipeline reference