/release-align

description: Align versions across multiple repositories according to release strategy. Analyzes conventional commits to suggest version bumps, detects version conflicts, validates cross-repo compatibility, and executes version alignment (updates package.json, creates git tags, updates changelogs). Supports lockstep, independent, and umbrella versioning strategies.

sw-release:align - Align Repository Versions

Align versions across multiple repositories according to your release strategy.

What This Command Does

1. **Analyzes Current Versions**: Reads current version from each repository 2. **Analyzes Commits**: Uses conventional commits to suggest version bumps 3. **Detects Conflicts**: Identifies version incompatibilities across repos 4. **Suggests Bumps**: Recommends new versions based on changes 5. **Validates Compatibility**: Ensures new versions are compatible 6. **Executes Alignment**: Updates versions, creates tags, updates changelogs

Usage

# Interactive alignment (prompts for confirmation)
sw-release:align

# Align specific repositories only
sw-release:align --repos frontend,backend

# Dry run (show what would change, don't execute)
sw-release:align --dry-run

# Force alignment (skip validation)
sw-release:align --force

# Align for specific strategy
sw-release:align --strategy lockstep
sw-release:align --strategy independent
sw-release:align --strategy umbrella

Workflow

Step 1: Analyze Current State

Scanning repositories...

frontend:
  Current: v4.2.0
  Location: ~/projects/myapp/frontend
  Git status: Clean ✓

backend:
  Current: v2.8.0
  Location: ~/projects/myapp/backend
  Git status: Clean ✓

api-gateway:
  Current: v3.1.0
  Location: ~/projects/myapp/api-gateway
  Git status: Uncommitted changes ✗

shared-lib:
  Current: v1.5.0
  Location: ~/projects/myapp/shared-lib
  Git status: Clean ✓

Blockers:
❌ api-gateway has uncommitted changes
   Action: Commit or stash changes before aligning

[Abort alignment]

Step 2: Analyze Commits

Analyzing commits since last release...

frontend (v4.2.0):
  Commits since v4.2.0: 18
  - Breaking changes: 1 (feat!: upgrade to React 18)
  - Features: 4
  - Bug fixes: 10
  - Other: 3 (docs, chore)

  Suggested: v5.0.0 (MAJOR)
  Rationale: Breaking change detected

backend (v2.8.0):
  Commits since v2.8.0: 12
  - Breaking changes: 0
  - Features: 3 (feat: add real-time notifications)
  - Bug fixes: 7
  - Other: 2

  Suggested: v2.9.0 (MINOR)
  Rationale: New features added

api-gateway (v3.1.0):
  Commits since v3.1.0: 22
  - Breaking changes: 2 (feat!: remove /v2 endpoints)
  - Features: 5
  - Bug fixes: 12
  - Other: 3

  Suggested: v4.0.0 (MAJOR)
  Rationale: Breaking changes detected

shared-lib (v1.5.0):
  Commits since v1.5.0: 3
  - Breaking changes: 0
  - Features: 0
  - Bug fixes: 3
  - Other: 0

  Suggested: v1.5.1 (PATCH)
  Rationale: Bug fixes only

Step 3: Check Alignment Strategy

Reading release strategy...
Location: .specweave/docs/internal/delivery/release-strategy.md

Strategy: Independent Versioning
- Each repository versions separately
- Only bump repos with changes
- Validate compatibility constraints

Applying strategy rules...
✓ frontend: Independent bump (v5.0.0)
✓ backend: Independent bump (v2.9.0)
✓ api-gateway: Independent bump (v4.0.0)
✓ shared-lib: Independent bump (v1.5.1)

Step 4: Validate Compatibility

Validating cross-repo compatibility...

Dependency Check 1: shared-lib versions
  frontend package.json: "shared-lib": "^1.5.0"
  Current shared-lib: v1.5.0
  Proposed shared-lib: v1.5.1
  Compatible? ✓ (within ^1.5.0 range)

Dependency Check 2: API versions
  frontend API client: Expects /api/v3
  api-gateway: Provides /api/v3, /api/v4 (removing /api/v2)
  Compatible? ✓ (v3 still supported)

Dependency Check 3: Database schema
  backend requires: Schema v12
  Current production: Schema v12
  Compatible? ✓

Overall: All compatibility checks passed ✓

Step 5: Review and Confirm

Proposed version alignment:

┌──────────────┬──────────┬──────────┬───────────────────────┐
│ Repository   │ Current  │ Proposed │ Reason                │
├──────────────┼──────────┼──────────┼───────────────────────┤
│ frontend     │ v4.2.0   │ v5.0.0   │ Breaking: React 18    │
│ backend      │ v2.8.0   │ v2.9.0   │ Feature: Notifications│
│ api-gateway  │ v3.1.0   │ v4.0.0   │ Breaking: Remove v2   │
│ shared-lib   │ v1.5.0   │ v1.5.1   │ Bug fixes             │
└──────────────┴──────────┴──────────┴───────────────────────┘

Breaking Changes Summary:
- frontend: React 16 → 18 (requires Node.js 18+)
- api-gateway: Removed /api/v2 endpoints (use /api/v3)

Actions to perform:
1. Update package.json versions
2. Create git tags
3. Update CHANGELOG.md files
4. Push tags to origin

? Proceed with alignment? [Yes / No / Edit]

Step 6: Execute Alignment

Executing version alignment...

frontend (v4.2.0 → v5.0.0):
  ✓ Updated package.json
  ✓ Generated CHANGELOG.md
  ✓ Created git tag v5.0.0
  ✓ Committed changes
  ✓ Pushed tag to origin

backend (v2.8.0 → v2.9.0):
  ✓ Updated package.json
  ✓ Generated CHANGELOG.md
  ✓ Created git tag v2.9.0
  ✓ Committed changes
  ✓ Pushed tag to origin

api-gateway (v3.1.0 → v4.0.0):
  ✓ Updated package.json
  ✓ Generated CHANGELOG.md
  ✓ Created git tag v4.0.0
  ✓ Committed changes
  ✓ Pushed tag to origin

shared-lib (v1.5.0 → v1.5.1):
  ✓ Updated package.json
  ✓ Generated CHANGELOG.md
  ✓ Created git tag v1.5.1
  ✓ Committed changes
  ✓ Pushed tag to origin

Version alignment complete! ✓

Next steps:
1. Create release increment: sw:increment "0080-product-v5-release"
2. Or trigger CI/CD: Git tags will trigger automated releases
3. Monitor: Check CI/CD pipelines for build/test/publish

Alignment Strategies

Lockstep Versioning

**All repos share same version**:

Strategy: Lockstep

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