specweave 1.0.593 → 2.0.3

package/plugins/specweave/commands/release-align.md

@@ -1,504 +0,0 @@
----
-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
-
-```bash
-# 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
-
-```markdown
-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
-
-```markdown
-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
-
-```markdown
-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
-
-```markdown
-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
-
-```markdown
-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
-
-```markdown
-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**:
-
-```markdown
-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
-```
-
-### Independent Versioning
-
-**Each repo versions separately**:
-
-```markdown
-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
-```
-
-### Umbrella Versioning
-
-**Product version spans service versions**:
-
-```markdown
-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}
-```
-
-## Version Conflict Detection
-
-**Example: Dependency Version Mismatch**
-
-```markdown
-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]
-```
-
-## Conventional Commits
-
-**This command relies on conventional commits**:
-
-```bash
-# 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**:
-- Scans commits: `git log <last-tag>..HEAD`
-- Parses commit messages
-- Categorizes: breaking / feature / fix / other
-- Suggests bump: MAJOR / MINOR / PATCH
-
-## Integration with Release Strategy
-
-**Reads strategy from**:
-```
-.specweave/docs/internal/delivery/release-strategy.md
-```
-
-**Uses strategy to**:
-- Determine alignment approach (lockstep/independent/umbrella)
-- Apply version bump rules
-- Validate compatibility constraints
-- Generate appropriate documentation
-
-## Multi-Project Support
-
-**For multi-project setups**:
-
-```bash
-# 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
-```
-
-## Best Practices
-
-**Before Aligning**:
-- Ensure all repos are clean (no uncommitted changes)
-- Pull latest changes from origin
-- Review conventional commits
-- Check release strategy is up-to-date
-
-**During Alignment**:
-- Use dry-run first to preview changes
-- Review version bumps carefully
-- Validate compatibility thoroughly
-- Document breaking changes
-
-**After Alignment**:
-- Monitor CI/CD pipelines
-- Create release increment
-- Update living docs
-- Notify team of new versions
-
-## Example Interactions
-
-### Lockstep Alignment
-
-```bash
-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]
-```
-
-### Independent Alignment with Conflict
-
-```bash
-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?
-```
-
-## Related Commands
-
-- `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 alignment
-
-## Dependencies
-
-**Required**:
-- Git (version control)
-- Release strategy document
-
-**Optional**:
-- NPM (`npm version`) - Automated versioning
-- Conventional Commits - Commit analysis
-- Semantic Release - Automation integration
-
----
-
-**Use this command** to ensure version consistency across repositories while following your project's release strategy.