/release-expert

description: Multi-repo release expert - version alignment, semantic versioning, release coordination, dependency management, release waves, RC lifecycle (alpha/beta/rc), brownfield detection, rollback planning. Use for synchronized releases, version alignment, or release strategy.
version: 1.0.0
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
model: opus
context: fork

Release Expert

Multi-repo release orchestration, version alignment, RC lifecycle management, and release strategy.

Core Capabilities

1. **Semantic versioning** enforcement and version bump suggestions 2. **Multi-repo version alignment** (lockstep/independent/umbrella strategies) 3. **Version conflict detection** and compatibility validation 4. **Release dependency management** and wave-based coordination 5. **RC lifecycle management** (alpha/beta/rc/final) 6. **Brownfield strategy detection** from existing projects 7. **Rollback planning** with reverse wave ordering 8. **Version matrix management** for umbrella releases

---

Semantic Versioning (Semver)

**Format**: `MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]`

**Version Bump Rules**:

MAJOR (1.0.0 -> 2.0.0):
  - Breaking changes (incompatible API)
  - Remove features
  - Change behavior of existing features
  Examples:
    - Remove deprecated endpoints
    - Change function signatures
    - Modify data formats

MINOR (1.0.0 -> 1.1.0):
  - New features (backward compatible)
  - Add endpoints/functions
  - Deprecate (but don't remove) features
  Examples:
    - Add new API endpoints
    - Add optional parameters
    - New module exports

PATCH (1.0.0 -> 1.0.1):
  - Bug fixes (no API changes)
  - Performance improvements
  - Documentation updates
  Examples:
    - Fix null pointer error
    - Optimize database query
    - Update README

**Pre-Release Tags**:

Alpha: 1.0.0-alpha.1  # Early development (unstable)
Beta:  1.0.0-beta.1   # Feature complete (testing)
RC:    1.0.0-rc.1     # Release candidate (near production)
Final: 1.0.0          # Production release

---

Version Alignment Strategies

Lockstep Versioning (all repos share version)

Strategy: Lockstep
When to Use: Tight coupling, small team, shared breaking changes

Current State:
  - frontend: v2.5.0
  - backend: v2.5.0
  - api: v2.5.0

Rules:
  - ALL repos MUST bump together
  - Use highest bump type (if any repo needs MAJOR, all bump MAJOR)
  - Version always stays in sync

Independent Versioning (each repo has own version)

Strategy: Independent
When to Use: Loose coupling, autonomous teams, frequent releases

Current State:
  - frontend: v4.2.0
  - backend: v2.8.0
  - api: v3.1.0

Rules:
  - Each repo versions independently
  - Only bump repos with changes
  - Validate compatibility constraints

Umbrella Versioning (product version + service versions)

Strategy: Umbrella
When to Use: Product milestones, services evolve at different rates

Product: v5.0.0 (umbrella)
  - frontend: v4.2.0
  - backend: v2.8.0
  - api: v3.1.0

Rules:
  - Product version bumps for milestones
  - Services version independently
  - Track matrix in release-strategy.md

---

Conventional Commits Analysis

**Analyzes commits to suggest version bumps**:

# MAJOR (breaking change)
feat!: remove legacy authentication
BREAKING CHANGE: Old auth endpoints removed

# MINOR (new feature)
feat: add real-time notifications
feat(api): add WebSocket support

# PATCH (bug fix)
fix: prevent null pointer in user service
fix(ui): correct button alignment
perf: optimize database queries

# No version bump
docs: update README
chore: upgrade dependencies
style: format code
refactor: extract helper function
test: add unit tests

**Version Bump Calculation**:

# Example commit history
git log v2.5.0..HEAD --oneline

feat!: remove deprecated endpoints       # BREAKING
feat: add dark mode toggle               # FEATURE
fix: prevent crash on logout             # BUGFIX
docs: update API documentation           # NO BUMP

# Analysis: Breaking changes detected -> MAJOR bump
# Suggested: v2.5.0 -> v3.0.0

---

Version Conflict Detection

Dependency Version Conflicts

# Scenario: Two services depend on different versions of shared-lib

service-a:
  package.json: "shared-lib": "^2.0.0"
  Currently using: v2.0.0

service-b:
  package.json: "shared-lib": "^1.5.0"
  Currently using: v1.8.0

Conflict:
  - service-a requires shared-lib v2.x (breaking changes)
  - service-b still on shared-lib v1.x (outdated)
  - Cannot release until service-b upgrades

Resolution:
  1. Update service-b to "shared-lib": "^2.0.0"
  2. Test service-b with shared-lib v2.0.0
  3. Release service-b
  4. Then proceed with coordinated release

API Contract Version Conflicts

# Scenario: Frontend expects API v3, but backend provides v2

frontend:
  api-client: v3.0.0
  Expects: POST /api/v3/users

backend:
  Current version: v2.8.0
  Provides: POST /api/v2/users

Conflict:
  - Frontend expects v3 API
  - Backend hasn't released v3 yet

Resolution:
  1. Release backend v3.0.0 first (Wave 1)
  2. Verify API v3 endpoints work
  3. Then release frontend v5.0.0 (Wave 2)

---

Release Dependency Management

# Build-time dependencies
shared-lib: v2.0.0
  - service-a: v3.1.0 (depends on shared-lib)
  - service-b: v2.5.0 (depends on shared-lib)

# Runtime dependencies
auth-service: v1.8.0
  - api-gateway: v2.0.0 (calls auth-service)
    - frontend: v3.2.0 (calls api-gateway)

**Release Order Calculation**: 1. Build dependency graph 2. Topological sort for correct order 3. Identify circular dependencies (error) 4. Generate release waves

---

Release Waves

### Wave 1 (Foundations)
- [ ] shared-lib: v2.0.0 -> v3.0.0
- [ ] database-migrations: v9 -> v10

### Wave 2 (Backend Services)
- [ ] auth-service: v1.8.0 -> v2.0.0 (depends: shared-lib v3.0.0)
- [ ] user-service: v1.5.0 -> v2.0.0 (depends: schema v10)

### Wave 3 (API Lay