Platform Release Coordination

Purpose: Orchestrate releases across multiple repositories as a unified platform version.

When to Use: Multi-repo architectures where services must release together (umbrella versioning).

---

Commands

Create Platform RC

/sw-release:platform create <platform-version>

Example:

/sw-release:platform create v3.0.0

What it does:

1. Validates all repos have clean working directories
2. Creates release/v* branches in all repos (GitFlow)
3. Aligns versions across repos (using semantic versioning)
4. Tags RC.1 in all repos: v5.0.0-rc.1, v2.9.0-rc.1, etc.
5. Updates platform manifest: .specweave/platform-releases.json
6. Creates version matrix: .specweave/docs/internal/delivery/version-matrix.md

Output:

🚀 Creating Platform Release: v3.0.0

Step 1: Validating repositories...
   ✓ frontend: Clean (current: v4.2.0)
   ✓ backend: Clean (current: v2.8.0)
   ✓ api-gateway: Clean (current: v3.1.0)

Step 2: Analyzing changes...
   📊 frontend: 12 commits (3 breaking, 5 features, 4 fixes) → Suggest v5.0.0
   📊 backend: 8 commits (0 breaking, 7 features, 1 fix) → Suggest v2.9.0
   📊 api-gateway: 15 commits (2 breaking, 8 features, 5 fixes) → Suggest v4.0.0

Step 3: Creating release branches...
   ✓ frontend: release/v5.0.0
   ✓ backend: release/v2.9.0
   ✓ api-gateway: release/v4.0.0

Step 4: Tagging RC.1...
   ✓ frontend: v5.0.0-rc.1
   ✓ backend: v2.9.0-rc.1
   ✓ api-gateway: v4.0.0-rc.1

Step 5: Updating platform manifest...
   ✓ Created .specweave/platform-releases.json

Step 6: Updating version matrix...
   ✓ Created .specweave/docs/internal/delivery/version-matrix.md

✅ Platform v3.0.0-rc.1 created!

Next steps:
1. Deploy to staging
2. Run E2E tests
3. If tests pass: /sw-release:platform promote v3.0.0-rc.1
4. If tests fail: /sw-release:platform iterate v3.0.0-rc.1

---

Iterate Platform RC

/sw-release:platform iterate <platform-rc-version>

Example:

/sw-release:platform iterate v3.0.0-rc.1

What it does:

1. Identifies which repos need fixes
2. Bumps RC number (rc.1 → rc.2)
3. Tags new RC in affected repos only
4. Updates platform manifest

Output:

🔄 Iterating Platform RC: v3.0.0-rc.1

Which repos need fixes?
[x] frontend
[ ] backend (no changes needed)
[x] api-gateway

Creating RC.2 for changed repos:
   ✓ frontend: v5.0.0-rc.2
   ✓ api-gateway: v4.0.0-rc.2
   ℹ️  backend: v2.9.0-rc.1 (unchanged)

✅ Platform v3.0.0-rc.2 created!

---

Promote Platform RC to Production

/sw-release:platform promote <platform-rc-version>

Example:

/sw-release:platform promote v3.0.0-rc.3

What it does:

1. Validates all RCs passed tests
2. Merges release branches to main (GitFlow)
3. Tags final versions (removes -rc.N suffix)
4. Merges main back to develop (GitFlow)
5. Deletes release branches (optional)
6. Updates platform manifest with "released" status
7. Updates version matrix
8. Tracks DORA metrics

Pre-Flight Checklist:

• ✅ All E2E tests passing
• ✅ Performance benchmarks met
• ✅ Security scan clean
• ✅ Stakeholder approval received
• ✅ Canary deployment successful (if applicable)

Output:

🎉 Promoting Platform RC to Production: v3.0.0-rc.3

Pre-Flight Checks:
   ✓ All repos on latest RC
   ✓ Tests passing: frontend ✅, backend ✅, api-gateway ✅
   ✓ No blocking issues

Step 1: Merging to main...
   ✓ frontend: release/v5.0.0 → main
   ✓ backend: release/v2.9.0 → main
   ✓ api-gateway: release/v4.0.0 → main

Step 2: Tagging final versions...
   ✓ frontend: v5.0.0
   ✓ backend: v2.9.0
   ✓ api-gateway: v4.0.0

Step 3: Merging back to develop...
   ✓ frontend: main → develop
   ✓ backend: main → develop
   ✓ api-gateway: main → develop

Step 4: Cleaning up release branches...
   ✓ frontend: Deleted release/v5.0.0
   ✓ backend: Deleted release/v2.9.0
   ✓ api-gateway: Deleted release/v4.0.0

Step 5: Updating platform manifest...
   ✓ Status: released

Step 6: Tracking DORA metrics...
   ✓ Deployment frequency updated
   ✓ Lead time calculated
   ✓ Dashboard updated

✅ Platform v3.0.0 released to production!

Platform Version Matrix:
  Product: v3.0.0
  ├─ frontend: v5.0.0
  ├─ backend: v2.9.0
  └─ api-gateway: v4.0.0

Deployment URLs:
  - Production: https://app.example.com
  - Docs: .specweave/docs/internal/delivery/version-matrix.md

---

Platform Release Status

/sw-release:platform status [platform-version]

Example:

/sw-release:platform status v3.0.0

Output:

📊 Platform Release Status: v3.0.0

Status: 🟡 In Progress (RC.2)

Service Versions:
  ✓ frontend: v5.0.0-rc.2 (from v4.2.0)
  ✓ backend: v2.9.0-rc.1 (from v2.8.0)
  ✓ api-gateway: v4.0.0-rc.2 (from v3.1.0)

RC History:
  - v3.0.0-rc.1: Created 2025-11-11 10:00 UTC
  - v3.0.0-rc.2: Created 2025-11-11 14:30 UTC (frontend, api-gateway fixed)

Tests:
  ✓ frontend: All passing
  ✓ backend: All passing
  🔴 api-gateway: 2 E2E tests failing

Blockers:
  - api-gateway: Auth flow broken (issue #145)

Next Steps:
  1. Fix api-gateway auth flow
  2. Create RC.3: /sw-release:platform iterate v3.0.0-rc.2
  3. Re-test
  4. Promote: /sw-release:platform promote v3.0.0-rc.3

---

Platform Manifest Format

Location: .specweave/platform-releases.json

{
  "v3.0.0": {
    "status": "rc",
    "currentRC": "rc.2",
    "created": "2025-11-11T10:00:00Z",
    "services": {
      "frontend": {
        "version": "v5.0.0-rc.2",
        "previousVersion": "v4.2.0",
        "changeType": "major",
        "releaseNotes": "Breaking changes: New auth API"
      },
      "backend": {
        "version": "v2.9.0-rc.1",
        "previousVersion": "v2.8.0",
        "changeType": "minor",
        "releaseNotes": "Added dark mode support"
      },
      "api-gateway": {
        "version": "v4.0.0-rc.2",
        "previousVersion": "v3.1.0",
        "changeType": "major",
        "releaseNotes": "Breaking changes: Removed legacy endpoints"
      }
    },
    "rcHistory": [
      {
        "rc": "rc.1",
        "created": "2025-11-11T10:00:00Z",
        "services": {
          "frontend": "v5.0.0-rc.1",
          "backend": "v2.9.0-rc.1",
          "api-gateway": "v4.0.0-rc.1"
        }
      },
      {
        "rc": "rc.2",
        "created": "2025-11-11T14:30:00Z",
        "services": {
          "frontend": "v5.0.0-rc.2",
          "backend": "v2.9.0-rc.1",
          "api-gateway": "v4.0.0-rc.2"
        },
        "changes": ["frontend: Fixed auth bug", "api-gateway: Fixed CORS issue"]
      }
    ]
  }
}

---

Version Matrix Document

Location: .specweave/docs/internal/delivery/version-matrix.md

Content:

# Platform Version Matrix

**Last Updated**: 2025-11-11 15:00 UTC

## Current Production

**Platform Version**: v2.0.0
**Released**: 2025-10-15

| Service | Version | Changelog |
|---------|---------|-----------|
| frontend | v4.2.0 | Added user preferences |
| backend | v2.8.0 | Performance improvements |
| api-gateway | v3.1.0 | Rate limiting updates |

---

## In Progress

**Platform Version**: v3.0.0-rc.2
**Status**: Testing

| Service | RC Version | Change Type | Release Notes |
|---------|------------|-------------|---------------|
| frontend | v5.0.0-rc.2 | MAJOR | Breaking: New auth API |
| backend | v2.9.0-rc.1 | MINOR | Dark mode support |
| api-gateway | v4.0.0-rc.2 | MAJOR | Breaking: Removed legacy endpoints |

**Blockers**: api-gateway auth flow (issue #145)

---

## Release History

### v2.0.0 (2025-10-15)
- frontend: v4.2.0
- backend: v2.8.0
- api-gateway: v3.1.0

### v1.5.0 (2025-09-01)
- frontend: v4.0.0
- backend: v2.7.0
- api-gateway: v3.0.0

(Complete history...)

---

Configuration

In .specweave/config.json:

{
  "release": {
    "platformMode": true,
    "repositories": [
      {
        "name": "frontend",
        "path": "../frontend",
        "git": "https://github.com/org/frontend.git"
      },
      {
        "name": "backend",
        "path": "../backend",
        "git": "https://github.com/org/backend.git"
      },
      {
        "name": "api-gateway",
        "path": "../api-gateway",
        "git": "https://github.com/org/api-gateway.git"
      }
    ],
    "gitflow": {
      "enabled": true,
      "releaseBranchPrefix": "release/",
      "deleteAfterMerge": true
    }
  }
}

---

Best Practices

When to Use Platform Releases:

• ✅ Services have tight coupling (breaking changes affect multiple repos)
• ✅ Product milestones important (v3.0.0 marketing launch)
• ✅ Need coordinated testing (E2E tests span services)
• ✅ Compliance requirements (audit trail for version combinations)

When NOT to Use:

• ❌ Services are fully independent (no coupling)
• ❌ Different release cadences (frontend weekly, backend monthly)
• ❌ Large number of services (>10 repos - use independent versioning)

RC Best Practices:

• Create RC.1 early (at least 1 week before planned release)
• Limit RC iterations (ideally ≤3, if >5 something is wrong)
• Test cross-service integration thoroughly
• Document all changes between RCs

---

Troubleshooting

Issue: Git conflicts during merge

# Solution: Resolve conflicts manually, then resume
git add .
git commit -m "Resolved conflicts"
/sw-release:platform promote v3.0.0-rc.3 --resume

Issue: One service fails tests

# Solution: Fix the service, create new RC
# (Don't bump other services that passed)
/sw-release:platform iterate v3.0.0-rc.2

Issue: Need to rollback

# Solution: Revert main to previous tag, create hotfix
git revert <commit>
/sw-release:platform create v3.0.1

---

Related Documentation

• Release Strategy
• Version Matrix
• GitFlow Guide
• DORA Metrics

---

Note: This command integrates with existing SpecWeave increment workflow. Each platform release should have its own increment (e.g., 0050-platform-v3-release).