---
description: "Coordinate multi-repo platform releases with synchronized versioning, RC workflow, and GitFlow integration. Usage: sw-release:platform create|promote|status"
---

# 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

```bash
sw-release:platform create <platform-version>
```

**Example**:
```bash
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

```bash
sw-release:platform iterate <platform-rc-version>
```

**Example**:
```bash
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

```bash
sw-release:platform promote <platform-rc-version>
```

**Example**:
```bash
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

```bash
sw-release:platform status [platform-version]
```

**Example**:
```bash
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`

```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**:
```markdown
# 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`**:

```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
```bash
# 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
```bash
# 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
```bash
# Solution: Revert main to previous tag, create hotfix
git revert <commit>
sw-release:platform create v3.0.1
```

---

## Related Documentation

- [Release Strategy](../../docs/internal/delivery/release-strategy.md)
- [Version Matrix](../../docs/internal/delivery/version-matrix.md)
- [GitFlow Guide](../../docs/internal/delivery/guides/gitflow.md)
- [DORA Metrics](../../docs/internal/delivery/dora-dashboard.md)

---

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