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.
Align versions across multiple repositories according to your release strategy. Analyzes conventional commits to suggest version bumps, detects conflicts, validates compatibility, and executes alignment with lockstep, independent, or umbrella strategies.
/plugin marketplace add anton-abyzov/specweave/plugin install sw-release@specweaveAlign versions across multiple repositories according to your release strategy.
# 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
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]
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
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)
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 ✓
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]
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
All repos share same version:
Strategy: Lockstep
Current State:
- frontend: v2.5.0
- backend: v2.5.0
- api: v2.5.0
Analysis:
- frontend: Breaking change detected
- backend: Bug fix
- api: No changes
Alignment Rule: Use highest bump type (MAJOR)
Proposed:
- frontend: v3.0.0 (breaking)
- backend: v3.0.0 (forced, no changes)
- api: v3.0.0 (forced, no changes)
⚠️ Warning: backend and api have no changes but must bump for lockstep
Each repo versions separately:
Strategy: Independent
Current State:
- frontend: v4.2.0
- backend: v2.8.0
- api: v3.1.0
Analysis:
- frontend: Breaking change
- backend: New feature
- api: Bug fix
Alignment Rule: Bump each independently
Proposed:
- frontend: v5.0.0 (major)
- backend: v2.9.0 (minor)
- api: v3.1.1 (patch)
✓ Each repo versions at its own pace
Product version spans service versions:
Strategy: Umbrella
Current Product: v4.0.0
- frontend: v4.2.0
- backend: v2.8.0
- api: v3.1.0
Analysis:
- frontend: Breaking change (React 18)
- backend: New feature (notifications)
- api: Breaking change (remove v2)
Alignment Rule: Product major bump (any service has breaking)
Proposed Product: v5.0.0
- frontend: v5.0.0
- backend: v2.9.0
- api: v4.0.0
Updated Version Matrix:
Product v5.0.0 = {frontend: v5.0.0, backend: v2.9.0, api: v4.0.0}
Example: Dependency Version Mismatch
Validating compatibility...
❌ Conflict detected!
service-a:
package.json: "shared-lib": "^2.0.0"
Requires: shared-lib v2.x
service-b:
package.json: "shared-lib": "^1.5.0"
Requires: shared-lib v1.x
Current:
shared-lib: v2.0.0
Problem:
service-b is incompatible with shared-lib v2.0.0
(requires v1.x, but v2.0.0 has breaking changes)
Resolution Options:
1. Update service-b to use "shared-lib": "^2.0.0"
2. Test service-b with shared-lib v2.0.0
3. Fix any breaking changes
4. Then retry alignment
[Abort alignment]
This command relies on conventional commits:
# Breaking change (MAJOR bump)
feat!: upgrade to React 18
BREAKING CHANGE: Requires Node.js 18+
# Feature (MINOR bump)
feat: add real-time notifications
feat(api): add WebSocket support
# Bug fix (PATCH bump)
fix: prevent null pointer in user service
fix(ui): correct button alignment
# No version bump
docs: update README
chore: upgrade dependencies
style: format code
refactor: extract helper function
test: add unit tests
Commit Analysis:
git log <last-tag>..HEADReads strategy from:
.specweave/docs/internal/delivery/release-strategy.md
Uses strategy to:
For multi-project setups:
# Align versions within a specific project
/sw-release:align --project frontend-team
# Align across all projects
/sw-release:align --all-projects
# Align specific project's repos only
/sw-release:align --project backend-team --repos api,database
Before Aligning:
During Alignment:
After Alignment:
User: /sw-release:align --strategy lockstep
Release Manager: Analyzing repositories with lockstep strategy...
Current State:
- service-a: v2.5.0
- service-b: v2.5.0
- service-c: v2.5.0
Commit Analysis:
- service-a: Breaking change detected
- service-b: Bug fix only
- service-c: No changes
Lockstep Rule: All repos must bump together (use highest: MAJOR)
Proposed:
- service-a: v3.0.0 (breaking change)
- service-b: v3.0.0 (forced, for alignment)
- service-c: v3.0.0 (forced, for alignment)
⚠️ Note: service-b and service-c have no changes but must bump for lockstep
? Proceed? [Yes / No]
User: /sw-release:align
Release Manager: Analyzing repositories with independent strategy...
...
Validating compatibility...
❌ Conflict detected!
frontend requires: api-client v4.0.0
api-gateway provides: v3.1.0 (proposed bump to v3.1.1)
Problem: Frontend expects v4 API, but gateway hasn't released v4 yet
Resolution:
Option 1: Release api-gateway v4.0.0 first (breaking changes)
Option 2: Update frontend to use api-client v3.x (delay v4 features)
Option 3: Coordinate release (release gateway v4 with frontend v5)
Recommendation: Option 3 (coordinated release)
Would you like me to create a coordinated release increment?
/sw-release:init - Initialize release strategy/sw-release:rc - Create release candidates for aligned versions/sw-release:coordinate - Plan coordinated multi-repo release/sw-release:publish - Execute release after alignmentRequired:
Optional:
npm version) - Automated versioningUse this command to ensure version consistency across repositories while following your project's release strategy.