Initial commit
This commit is contained in:
Zhongwei Li
505
commands/specweave-release-align.md
Normal file
505
commands/specweave-release-align.md
Normal file
@@ -0,0 +1,505 @@
|
||||
---
|
||||
name: specweave-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.
|
||||
---
|
||||
|
||||
# /specweave-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)
|
||||
/specweave-release:align
|
||||
|
||||
# Align specific repositories only
|
||||
/specweave-release:align --repos frontend,backend
|
||||
|
||||
# Dry run (show what would change, don't execute)
|
||||
/specweave-release:align --dry-run
|
||||
|
||||
# Force alignment (skip validation)
|
||||
/specweave-release:align --force
|
||||
|
||||
# Align for specific strategy
|
||||
/specweave-release:align --strategy lockstep
|
||||
/specweave-release:align --strategy independent
|
||||
/specweave-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: /specweave: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
|
||||
/specweave-release:align --project frontend-team
|
||||
|
||||
# Align across all projects
|
||||
/specweave-release:align --all-projects
|
||||
|
||||
# Align specific project's repos only
|
||||
/specweave-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: /specweave-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: /specweave-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
|
||||
|
||||
- `/specweave-release:init` - Initialize release strategy
|
||||
- `/specweave-release:rc` - Create release candidates for aligned versions
|
||||
- `/specweave-release:coordinate` - Plan coordinated multi-repo release
|
||||
- `/specweave-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.
|
||||
Reference in New Issue
Block a user