Initial commit
This commit is contained in:
Zhongwei Li
579
skills/version-aligner/SKILL.md
Normal file
579
skills/version-aligner/SKILL.md
Normal file
@@ -0,0 +1,579 @@
|
||||
---
|
||||
name: version-aligner
|
||||
description: Aligns versions across multiple repositories according to release strategy (lockstep, independent, umbrella). Handles semantic versioning constraints, detects version conflicts, suggests version bumps based on conventional commits, validates cross-repo compatibility, manages version matrices for umbrella releases. Activates for version alignment, align versions, version sync, semver, version conflicts, version bump, version compatibility, cross-repo versions, umbrella version matrix, lockstep versioning.
|
||||
---
|
||||
|
||||
# Version Aligner
|
||||
|
||||
**Expertise**: Multi-repository version alignment, semantic versioning, version conflict detection, and compatibility validation.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
### 1. Semantic Versioning (Semver)
|
||||
|
||||
**Enforces semver rules**:
|
||||
|
||||
**Format**: `MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]`
|
||||
|
||||
**Version Bump Rules**:
|
||||
```yaml
|
||||
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**:
|
||||
```yaml
|
||||
# Alpha: Early development (unstable)
|
||||
1.0.0-alpha.1, 1.0.0-alpha.2, ...
|
||||
|
||||
# Beta: Feature complete (testing)
|
||||
1.0.0-beta.1, 1.0.0-beta.2, ...
|
||||
|
||||
# RC: Release candidate (near production)
|
||||
1.0.0-rc.1, 1.0.0-rc.2, ...
|
||||
|
||||
# Final: Production release
|
||||
1.0.0
|
||||
```
|
||||
|
||||
### 2. Version Alignment Strategies
|
||||
|
||||
**Lockstep Versioning** (all repos share version):
|
||||
|
||||
```yaml
|
||||
Strategy: Lockstep
|
||||
Current State:
|
||||
- frontend: v2.5.0
|
||||
- backend: v2.5.0
|
||||
- api: v2.5.0
|
||||
- shared: v2.5.0
|
||||
|
||||
Proposed Bump: MAJOR (breaking change in API)
|
||||
New State:
|
||||
- frontend: v3.0.0
|
||||
- backend: v3.0.0
|
||||
- api: v3.0.0
|
||||
- shared: v3.0.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):
|
||||
|
||||
```yaml
|
||||
Strategy: Independent
|
||||
Current State:
|
||||
- frontend: v4.2.0
|
||||
- backend: v2.8.0
|
||||
- api: v3.1.0
|
||||
- shared: v1.5.0
|
||||
|
||||
Changes:
|
||||
- frontend: Bug fix → PATCH bump
|
||||
- backend: New feature → MINOR bump
|
||||
- api: No changes → No bump
|
||||
- shared: Breaking change → MAJOR bump
|
||||
|
||||
New State:
|
||||
- frontend: v4.2.1 (patch)
|
||||
- backend: v2.9.0 (minor)
|
||||
- api: v3.1.0 (unchanged)
|
||||
- shared: v2.0.0 (major)
|
||||
|
||||
Rules:
|
||||
- Each repo versions independently
|
||||
- Only bump repos with changes
|
||||
- Validate compatibility constraints
|
||||
```
|
||||
|
||||
**Umbrella Versioning** (product version + service versions):
|
||||
|
||||
```yaml
|
||||
Strategy: Umbrella
|
||||
Product: v5.0.0 (umbrella)
|
||||
|
||||
Version Matrix:
|
||||
- frontend: v4.2.0
|
||||
- backend: v2.8.0
|
||||
- api: v3.1.0
|
||||
- shared: v1.5.0
|
||||
|
||||
Changes for Product v6.0.0:
|
||||
- frontend: v4.2.0 → v5.0.0 (major redesign)
|
||||
- backend: v2.8.0 → v2.9.0 (new endpoints)
|
||||
- api: v3.1.0 → v4.0.0 (breaking changes)
|
||||
- shared: v1.5.0 → v1.5.0 (no changes)
|
||||
|
||||
New Product: v6.0.0 (umbrella)
|
||||
- frontend: v5.0.0
|
||||
- backend: v2.9.0
|
||||
- api: v4.0.0
|
||||
- shared: v1.5.0
|
||||
|
||||
Rules:
|
||||
- Product version bumps for milestones
|
||||
- Services version independently
|
||||
- Track matrix in release-strategy.md
|
||||
```
|
||||
|
||||
### 3. Conventional Commits Analysis
|
||||
|
||||
**Analyzes commits to suggest version bumps**:
|
||||
|
||||
**Commit Patterns**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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
|
||||
chore: upgrade React to v18 # NO BUMP
|
||||
|
||||
# Analysis
|
||||
Breaking changes: 1 → MAJOR bump (v2.5.0 → v3.0.0)
|
||||
Features: 1 → Overridden by MAJOR
|
||||
Bug fixes: 1 → Overridden by MAJOR
|
||||
|
||||
# Suggested: v2.5.0 → v3.0.0
|
||||
```
|
||||
|
||||
### 4. Version Conflict Detection
|
||||
|
||||
**Detects incompatible versions**:
|
||||
|
||||
**Dependency Version Conflicts**:
|
||||
```yaml
|
||||
# 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**:
|
||||
```yaml
|
||||
# Scenario: Frontend expects API v3, but backend provides v2
|
||||
|
||||
frontend:
|
||||
api-client: v3.0.0
|
||||
Expects: POST /api/v3/users (new endpoint)
|
||||
|
||||
backend:
|
||||
Current version: v2.8.0
|
||||
Provides: POST /api/v2/users (old endpoint)
|
||||
|
||||
Conflict:
|
||||
- Frontend expects v3 API
|
||||
- Backend hasn't released v3 yet
|
||||
- Deployment will fail
|
||||
|
||||
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)
|
||||
```
|
||||
|
||||
### 5. Compatibility Validation
|
||||
|
||||
**Validates cross-repo compatibility**:
|
||||
|
||||
**Semver Range Checking**:
|
||||
```typescript
|
||||
// Example: Validate service-a can work with shared-lib versions
|
||||
|
||||
// service-a/package.json
|
||||
{
|
||||
"dependencies": {
|
||||
"shared-lib": "^2.0.0" // Allows 2.0.0 to <3.0.0
|
||||
}
|
||||
}
|
||||
|
||||
// Validation
|
||||
shared-lib v2.0.0 → Compatible ✓
|
||||
shared-lib v2.5.0 → Compatible ✓
|
||||
shared-lib v2.9.9 → Compatible ✓
|
||||
shared-lib v3.0.0 → Incompatible ✗ (MAJOR change)
|
||||
```
|
||||
|
||||
**API Contract Validation**:
|
||||
```yaml
|
||||
# OpenAPI spec comparison
|
||||
|
||||
api-gateway v2.8.0 (current):
|
||||
POST /api/v2/users:
|
||||
parameters:
|
||||
- name: email (required)
|
||||
- name: password (required)
|
||||
|
||||
api-gateway v3.0.0 (proposed):
|
||||
POST /api/v3/users:
|
||||
parameters:
|
||||
- name: email (required)
|
||||
- name: password (required)
|
||||
- name: phoneNumber (optional) # NEW (backward compatible)
|
||||
|
||||
Compatibility:
|
||||
- New optional field → Minor version bump (v2.8.0 → v2.9.0) ✗
|
||||
- But route changed (/v2 → /v3) → Major version bump (v3.0.0) ✓
|
||||
- Verdict: v3.0.0 is correct ✓
|
||||
```
|
||||
|
||||
### 6. Version Matrix Management
|
||||
|
||||
**Tracks versions for umbrella releases**:
|
||||
|
||||
**Version Matrix Document**:
|
||||
```markdown
|
||||
# Product Version Matrix
|
||||
|
||||
## v6.0.0 (Latest - 2025-01-15)
|
||||
- frontend: v5.0.0
|
||||
- backend: v2.9.0
|
||||
- api-gateway: v4.0.0
|
||||
- auth-service: v2.1.0
|
||||
- user-service: v2.0.0
|
||||
- order-service: v3.2.0
|
||||
- shared-lib: v2.0.0
|
||||
- database-schema: v12
|
||||
|
||||
## v5.0.0 (Previous - 2024-12-10)
|
||||
- frontend: v4.2.0
|
||||
- backend: v2.8.0
|
||||
- api-gateway: v3.1.0
|
||||
- auth-service: v2.0.0
|
||||
- user-service: v1.8.0
|
||||
- order-service: v3.1.0
|
||||
- shared-lib: v1.5.0
|
||||
- database-schema: v11
|
||||
|
||||
## Compatibility Matrix
|
||||
|
||||
| Product | Frontend | Backend | API Gateway | Shared Lib | Schema |
|
||||
|---------|----------|---------|-------------|------------|--------|
|
||||
| v6.0.0 | v5.0.0 | v2.9.0 | v4.0.0 | v2.0.0 | v12 |
|
||||
| v5.0.0 | v4.2.0 | v2.8.0 | v3.1.0 | v1.5.0 | v11 |
|
||||
| v4.0.0 | v3.5.0 | v2.5.0 | v2.8.0 | v1.2.0 | v10 |
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
### v6.0.0
|
||||
- API Gateway v3 → v4: Removed legacy /v2 endpoints
|
||||
- Shared Lib v1 → v2: Changed authentication interface
|
||||
- Schema v11 → v12: Added user_metadata table
|
||||
|
||||
### v5.0.0
|
||||
- Frontend v4 → v5: React 16 → 18 (requires Node.js 18+)
|
||||
- User Service v1 → v2: Changed user creation API
|
||||
```
|
||||
|
||||
### 7. Automated Version Bumping
|
||||
|
||||
**Suggests and executes version bumps**:
|
||||
|
||||
**Interactive Version Bump**:
|
||||
```bash
|
||||
# Command
|
||||
/specweave-release:align
|
||||
|
||||
# Interactive prompts
|
||||
? Which repositories to align?
|
||||
◉ frontend (v4.2.0)
|
||||
◉ backend (v2.8.0)
|
||||
◉ api-gateway (v3.1.0)
|
||||
◯ shared-lib (v2.0.0) - no changes
|
||||
|
||||
? Alignment strategy?
|
||||
◯ Lockstep (all repos same version)
|
||||
◉ Independent (bump changed repos only)
|
||||
◯ Umbrella (product milestone)
|
||||
|
||||
# Analysis
|
||||
Analyzing conventional commits since last release...
|
||||
|
||||
frontend (v4.2.0):
|
||||
- 12 commits since v4.2.0
|
||||
- Breaking changes: 1
|
||||
- Features: 3
|
||||
- Bug fixes: 5
|
||||
Suggested: v5.0.0 (MAJOR)
|
||||
|
||||
backend (v2.8.0):
|
||||
- 8 commits since v2.8.0
|
||||
- Features: 2
|
||||
- Bug fixes: 3
|
||||
Suggested: v2.9.0 (MINOR)
|
||||
|
||||
api-gateway (v3.1.0):
|
||||
- 15 commits since v3.1.0
|
||||
- Breaking changes: 2
|
||||
- Features: 4
|
||||
Suggested: v4.0.0 (MAJOR)
|
||||
|
||||
? Confirm version bumps?
|
||||
◉ frontend: v4.2.0 → v5.0.0
|
||||
◉ backend: v2.8.0 → v2.9.0
|
||||
◉ api-gateway: v3.1.0 → v4.0.0
|
||||
|
||||
[Yes / No / Edit]
|
||||
```
|
||||
|
||||
**Automated Execution**:
|
||||
```bash
|
||||
# Updates package.json
|
||||
npm version major # frontend
|
||||
npm version minor # backend
|
||||
npm version major # api-gateway
|
||||
|
||||
# Creates git tags
|
||||
git tag v5.0.0 (frontend)
|
||||
git tag v2.9.0 (backend)
|
||||
git tag v4.0.0 (api-gateway)
|
||||
|
||||
# Updates CHANGELOG.md
|
||||
# - Extracts commits since last tag
|
||||
# - Groups by type (breaking, features, fixes)
|
||||
# - Generates markdown
|
||||
|
||||
# Updates version matrix
|
||||
# - Adds new product version row
|
||||
# - Links to service versions
|
||||
# - Documents breaking changes
|
||||
```
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Ask me to**:
|
||||
|
||||
1. **Align versions across repos**:
|
||||
- "Align versions for all microservices"
|
||||
- "Sync versions before release"
|
||||
- "What versions should we bump to?"
|
||||
|
||||
2. **Detect version conflicts**:
|
||||
- "Check for version conflicts"
|
||||
- "Validate cross-repo compatibility"
|
||||
- "Are our dependencies aligned?"
|
||||
|
||||
3. **Suggest version bumps**:
|
||||
- "What version should we bump to?"
|
||||
- "Analyze commits for version bump"
|
||||
- "Calculate semver from commits"
|
||||
|
||||
4. **Manage version matrices**:
|
||||
- "Update version matrix"
|
||||
- "Show compatibility matrix"
|
||||
- "Track umbrella version history"
|
||||
|
||||
5. **Validate compatibility**:
|
||||
- "Can frontend v5.0.0 work with backend v2.8.0?"
|
||||
- "Check API contract compatibility"
|
||||
- "Validate dependency ranges"
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Semver Discipline**:
|
||||
- Never skip versions (v1.0.0 → v1.1.0, not v1.0.0 → v1.2.0)
|
||||
- Use pre-release tags for testing (v1.0.0-rc.1)
|
||||
- Document breaking changes clearly
|
||||
|
||||
**Dependency Management**:
|
||||
- Pin major versions ("^2.0.0" not "*")
|
||||
- Update dependencies regularly (avoid drift)
|
||||
- Test compatibility before bumping
|
||||
|
||||
**Version Matrix**:
|
||||
- Update after every product release
|
||||
- Link to ADRs for breaking changes
|
||||
- Track deprecation timelines
|
||||
|
||||
**Automation**:
|
||||
- Use conventional commits (enables automated analysis)
|
||||
- Automate changelog generation
|
||||
- Validate versions in CI/CD
|
||||
|
||||
## Integration Points
|
||||
|
||||
**Release Strategy Advisor**:
|
||||
- Reads alignment strategy from release-strategy.md
|
||||
- Adapts to lockstep/independent/umbrella
|
||||
|
||||
**Release Coordinator**:
|
||||
- Provides version bump suggestions
|
||||
- Validates compatibility before release
|
||||
- Updates version matrix post-release
|
||||
|
||||
**RC Manager**:
|
||||
- Handles pre-release version tags
|
||||
- Promotes RC to final version
|
||||
- Tracks RC version history
|
||||
|
||||
**Brownfield Analyzer**:
|
||||
- Detects existing version patterns
|
||||
- Extracts current version matrix
|
||||
- Suggests alignment improvements
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Independent Versioning
|
||||
|
||||
```bash
|
||||
# 1. Analyze changes
|
||||
/specweave-release:align
|
||||
|
||||
# 2. Review suggested bumps
|
||||
Frontend v4.2.0 → v5.0.0 (breaking changes)
|
||||
Backend v2.8.0 → v2.9.0 (new features)
|
||||
API v3.1.0 → v3.1.1 (bug fixes only)
|
||||
|
||||
# 3. Validate compatibility
|
||||
✓ Frontend v5.0.0 compatible with Backend v2.8.0+
|
||||
✓ Backend v2.9.0 compatible with API v3.1.0+
|
||||
✗ Shared-lib v1.5.0 outdated (requires v2.0.0)
|
||||
|
||||
# 4. Fix blocking issues
|
||||
Update Backend to use shared-lib v2.0.0
|
||||
|
||||
# 5. Execute version bumps
|
||||
✓ All versions aligned
|
||||
✓ Tags created
|
||||
✓ Changelogs updated
|
||||
```
|
||||
|
||||
### Umbrella Versioning
|
||||
|
||||
```bash
|
||||
# 1. Create product release
|
||||
/specweave:increment "0040-product-v6-release"
|
||||
|
||||
# 2. Analyze component versions
|
||||
Current umbrella: v5.0.0
|
||||
Proposed: v6.0.0 (major milestone)
|
||||
|
||||
# 3. Review version matrix
|
||||
Frontend: v4.2.0 → v5.0.0 (redesign)
|
||||
Backend: v2.8.0 → v2.9.0 (new API)
|
||||
API: v3.1.0 → v4.0.0 (breaking changes)
|
||||
Shared: v1.5.0 → v2.0.0 (breaking changes)
|
||||
|
||||
# 4. Validate umbrella bump
|
||||
Breaking changes detected → MAJOR bump correct ✓
|
||||
Product v5.0.0 → v6.0.0 ✓
|
||||
|
||||
# 5. Update version matrix
|
||||
.specweave/docs/internal/delivery/version-matrix.md updated ✓
|
||||
```
|
||||
|
||||
## Commands Integration
|
||||
|
||||
Works with release commands:
|
||||
|
||||
- `/specweave-release:align` - Interactive version alignment
|
||||
- `/specweave-release:validate-versions` - Check compatibility
|
||||
- `/specweave-release:bump <repo> <type>` - Bump specific repo
|
||||
- `/specweave-release:matrix` - Show version matrix
|
||||
|
||||
## Dependencies
|
||||
|
||||
**Required**:
|
||||
- Git (version tags)
|
||||
- Semver library (version parsing)
|
||||
- SpecWeave core (living docs)
|
||||
|
||||
**Optional**:
|
||||
- NPM (`npm version`) - Automated bumping
|
||||
- Conventional Commits (commit analysis)
|
||||
- GitHub CLI (`gh release`) - Release notes
|
||||
|
||||
## Output
|
||||
|
||||
**Creates/Updates**:
|
||||
- `package.json` (version field)
|
||||
- Git tags (v1.0.0, v2.0.0, etc.)
|
||||
- `CHANGELOG.md` (release notes)
|
||||
- `.specweave/docs/internal/delivery/version-matrix.md`
|
||||
- Release strategy documentation
|
||||
|
||||
**Provides**:
|
||||
- Version bump suggestions
|
||||
- Compatibility validation report
|
||||
- Version conflict detection
|
||||
- Dependency graph
|
||||
- Version history
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Version alignment is critical for multi-repo architectures. Always:
|
||||
- Follow semantic versioning strictly
|
||||
- Validate compatibility before releasing
|
||||
- Document breaking changes clearly
|
||||
- Update version matrices regularly
|
||||
- Automate where possible (conventional commits + semantic-release)
|
||||
|
||||
**Goal**: Consistent, predictable versioning across all repositories with clear compatibility guarantees.
|
||||
Reference in New Issue
Block a user