085445e730
- Introduced RELEASE_VISUAL_GUIDE.md for a visual overview of the release pipeline, including development, staging, and production phases. - Created RELEASE_WORKFLOW.md detailing step-by-step release procedures for single and multi-product releases, including hotfix processes. - Added VERSION_FILES_REFERENCE.md to outline all necessary version file updates for each product during releases, ensuring consistency and completeness.
383 lines
17 KiB
Markdown
383 lines
17 KiB
Markdown
# Release Process Visual Guide
|
|
|
|
## 🔄 Release Pipeline Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ KROW WORKFORCE RELEASE PIPELINE │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─ DEVELOPMENT PHASE ────────────────────────────────────────────┐
|
|
│ │
|
|
│ Feature Branch Development │
|
|
│ ↓ │
|
|
│ Code Review & Testing │
|
|
│ ↓ │
|
|
│ Merge to Main │
|
|
│ ↓ │
|
|
│ Automated Builds & Tests (GitHub Actions / CodeMagic) │
|
|
│ ↓ │
|
|
│ ✅ Main is always deployment-ready │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─ STAGING RELEASE ──────────────────────────────────────────────┐
|
|
│ │
|
|
│ 1. Create Release Branch (release/[product]-v[version]) │
|
|
│ 2. Bump Version Numbers │
|
|
│ 3. Update CHANGELOG │
|
|
│ 4. Create Git Tags: */staging-v[version] │
|
|
│ 5. Deploy to Staging Environment │
|
|
│ 6. Run QA Tests │
|
|
│ 7. Product Owner Sign-off │
|
|
│ │
|
|
│ Duration: 1 week minimum │
|
|
│ Cadence: Bi-weekly │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─ ISSUE? ──────────────────┐
|
|
│ ↓
|
|
│ Create Hotfix
|
|
│ Branch/Tag
|
|
│ (*/staging-v[X+1])
|
|
└─ FIX & RETEST ────────────┘
|
|
↓
|
|
┌─ PRODUCTION RELEASE ───────────────────────────────────────────┐
|
|
│ │
|
|
│ 1. Final Verification in Staging │
|
|
│ 2. Create Production Tags: */prod-v[version] │
|
|
│ 3. Deploy in Dependency Order: │
|
|
│ • DataConnect Schema (if applicable) │
|
|
│ • Command API │
|
|
│ • Core API │
|
|
│ • Web Dashboard │
|
|
│ • Staff Mobile │
|
|
│ • Client Mobile │
|
|
│ 4. Smoke Tests in Production │
|
|
│ 5. Create GitHub Release Page │
|
|
│ 6. Announce to Users │
|
|
│ 7. Monitor for 24 hours │
|
|
│ │
|
|
│ Duration: 1-2 hours deployment, 24-48 hours monitoring │
|
|
│ Cadence: Monthly or sprint-based │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────┘
|
|
|
|
Legend:
|
|
✅ = Ready state
|
|
→ = Next step
|
|
↓ = Dependency
|
|
```
|
|
|
|
---
|
|
|
|
## 📦 Product Dependency & Release Order
|
|
|
|
```
|
|
┌──────────────────────┐
|
|
│ DataConnect Schema │
|
|
│ (if applicable) │
|
|
└──────────┬───────────┘
|
|
│
|
|
┌──────────▼──────────┐
|
|
│ Backend Services │
|
|
│ │
|
|
├─ Command API │
|
|
└─ Core API │
|
|
│
|
|
┌──────────────┼──────────────┐
|
|
│ │ │
|
|
┌──────▼────┐ ┌──────▼────┐ ┌────▼──────┐
|
|
│ Web │ │ Staff │ │ Client │
|
|
│ Dashboard │ │ Mobile │ │ Mobile │
|
|
│ │ │ App │ │ App │
|
|
└───────────┘ └───────────┘ └───────────┘
|
|
|
|
Critical Path (Staging → Production):
|
|
1. DataConnect (if schema changes)
|
|
2. APIs (Command + Core) [parallel OK]
|
|
3. Web Dashboard [can wait for API confirmation]
|
|
4. Mobile Apps [independent, can deploy anytime]
|
|
|
|
Parallel Deployments (when safe):
|
|
• Both backend APIs can deploy in parallel
|
|
• Mobile apps can deploy in parallel
|
|
• Web + Mobile can deploy in parallel (if APIs stable)
|
|
|
|
Non-Blocking:
|
|
• Mobile can release without web changes
|
|
• Web can release without mobile changes
|
|
• Backend can release non-breaking API changes independently
|
|
```
|
|
|
|
---
|
|
|
|
## 🏷️ Git Tag Timeline Example
|
|
|
|
```
|
|
Release v1.0.0 Timeline (Coordinated)
|
|
|
|
2026-03-01 2026-03-08 2026-03-15 2026-03-22
|
|
│ │ │ │
|
|
├─ Code Freeze ├─ Staging Release ├─ Production ├─ Next Sprint
|
|
│ │ │ Release │
|
|
├─ Feature Branches ├─ */staging-v1.0.0 ├─ */prod-v1.0.0 │
|
|
│ → main │ │ │
|
|
│ ├─ QA Testing ├─ Deploy & Verify │
|
|
├─ All Tests # ├─ 24h Monitoring ├─ 48h Monitoring │
|
|
│ Green # │ │ │
|
|
│ ├─ Product Sign-off ✓ ├─ Users Notified │
|
|
└─ Ready ✓ └─ Approved for Prod └─ Stable ✓ │
|
|
|
|
Key Milestones:
|
|
# = All automated tests passing
|
|
✓ = Manual approval/sign-off
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Release Branch Structure
|
|
|
|
```
|
|
┌─────────────────── main (Protected) ──────────────────┐
|
|
│ │
|
|
│ feature/auth feature/payments │
|
|
│ ↓ ↓ │
|
|
│ ──●──●──●── ──●──●──●── ──●──●──●── ← Feature │
|
|
│ │ │ │ Branches │
|
|
│ ├──────┬─────┤ ┬──────┤ │
|
|
│ ↓ │ ↓ │ ↓ │
|
|
│ ────●──────●─────●─────●──────●───── ← Merge PRs │
|
|
│ │ │
|
|
│ ↓ │
|
|
│ release/staff-mobile-v0.2.0 ← Release Branch │
|
|
│ │ │
|
|
│ ├─ Bump version │
|
|
│ ├─ Update CHANGELOG │
|
|
│ ├─ Commit & merge back │
|
|
│ │ │
|
|
│ ────●●────────────────── ← Merge back to main │
|
|
│ │ │
|
|
│ ↓ │
|
|
│ TAG: staff-mobile/staging-v0.2.0 ← Staging Tag │
|
|
│ TAG: staff-mobile/prod-v0.2.0 ← Prod Tag │
|
|
│ │ │
|
|
│ (Deploy from tags) │
|
|
│ │
|
|
└────────────────────────────────────────────────────────┘
|
|
|
|
Key Points:
|
|
• main is always clean and deployable
|
|
• Feature branches never go to staging/prod
|
|
• Tags point to main (after merge)
|
|
• Releases == Git tags, not branches
|
|
• Hotfix branches created from prod tags
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 Multi-Product Release Coordination
|
|
|
|
```
|
|
Product Release States (Example: v1.0.0)
|
|
|
|
Staff Mobile:
|
|
├─ Dev build: ✅ staff-mobile/dev-v1.0.0 (deployed)
|
|
├─ Staging: ✅ staff-mobile/staging-v1.0.0 (testing)
|
|
└─ Production: 🔄 staff-mobile/prod-v1.0.0 (deploying)
|
|
|
|
Client Mobile:
|
|
├─ Dev build: ✅ client-mobile/dev-v1.0.0 (deployed)
|
|
├─ Staging: ✅ client-mobile/staging-v1.0.0 (testing)
|
|
└─ Production: 🔄 client-mobile/prod-v1.0.0 (deploying)
|
|
|
|
Web Dashboard:
|
|
├─ Dev build: ✅ web-dashboard/dev-v1.0.0 (deployed)
|
|
├─ Staging: ✅ web-dashboard/staging-v1.0.0 (testing)
|
|
└─ Production: ✅ web-dashboard/prod-v1.0.0 (live)
|
|
|
|
Command API:
|
|
├─ Dev build: ✅ command-api/dev-v1.0.0 (deployed)
|
|
├─ Staging: ✅ command-api/staging-v1.0.0 (testing)
|
|
└─ Production: ✅ command-api/prod-v1.0.0 (live)
|
|
|
|
Core API:
|
|
├─ Dev build: ✅ core-api/dev-v1.0.0 (deployed)
|
|
├─ Staging: ✅ core-api/staging-v1.0.0 (testing)
|
|
└─ Production: ✅ core-api/prod-v1.0.0 (live)
|
|
|
|
Legend:
|
|
✅ = Released and stable
|
|
🔄 = In progress
|
|
⏳ = Waiting for approval
|
|
⛔ = Blocked/awaiting fix
|
|
|
|
|
|
Sync Points (when to coordinate):
|
|
1. Before moving staging → prod (all ready?)
|
|
2. During prod deployment (follow order)
|
|
3. Post-release (all working?)
|
|
4. If hotfix needed (which products affected?)
|
|
```
|
|
|
|
---
|
|
|
|
## 🚨 Hotfix Release Flow
|
|
|
|
```
|
|
Production Issue Detected
|
|
│
|
|
↓
|
|
┌─────────────────┐
|
|
│ Is it critical? │
|
|
└────┬────────┬───┘
|
|
│ YES │ NO
|
|
↓ └─→ Plan for next release
|
|
|
|
┌─────────────────────────┐
|
|
│ Create Hotfix Branch │
|
|
│ (from prod tag) │
|
|
└──────────┬──────────────┘
|
|
│
|
|
↓
|
|
┌─────────────────────────┐
|
|
│ Make Fix │
|
|
│ Test locally │
|
|
└──────────┬──────────────┘
|
|
│
|
|
↓
|
|
┌─────────────────────────┐
|
|
├─ Bump PATCH version │
|
|
│ (e.g., 0.1.0 → 0.1.1) │
|
|
├─ Update CHANGELOG │
|
|
├─ Commit to hotfix branch│
|
|
└──────────┬──────────────┘
|
|
│
|
|
↓
|
|
┌─────────────────────────┐
|
|
│ Code Review (expedited) │
|
|
│ Approval + merge │
|
|
└──────────┬──────────────┘
|
|
│
|
|
↓
|
|
┌─────────────────────────┐
|
|
│ Create Tag │
|
|
│ */prod-v0.1.1 │
|
|
└──────────┬──────────────┘
|
|
│
|
|
↓
|
|
┌─────────────────────────┐
|
|
│ Deploy to Production │
|
|
│ (High priority) │
|
|
└──────────┬──────────────┘
|
|
│
|
|
↓
|
|
┌─────────────────────────┐
|
|
│ Verify Fix │
|
|
│ Monitor 24h │
|
|
└──────────┬──────────────┘
|
|
│
|
|
↓
|
|
┌─────────────────────────┐
|
|
│ Communicate to Users │
|
|
│ Incident Report │
|
|
└──────────┬──────────────┘
|
|
│
|
|
↓
|
|
✅ Resolved
|
|
|
|
Speed target: 4-8 hours total (from detection to production verification)
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Version Matrix Dashboard
|
|
|
|
Create in your team wiki/notion:
|
|
|
|
```
|
|
╔════════════════════════════════╦═══════════╦═══════════╦═══════════╗
|
|
║ Product ║ Dev ║ Staging ║ Prod ║
|
|
╠════════════════════════════════╬═══════════╬═══════════╬═══════════╣
|
|
║ Staff Mobile ║ 0.2.1 ║ 0.2.0 ║ 0.1.0 ║
|
|
║ Client Mobile ║ 0.2.1 ║ 0.2.0 ║ 0.1.0 ║
|
|
║ Web Dashboard ║ 0.1.0 ║ 0.0.0 ║ — ║
|
|
║ Command API ║ 0.2.0 ║ 0.2.0-rc1 ║ 0.1.0 ║
|
|
║ Core API ║ 0.2.0 ║ 0.2.0-rc1 ║ 0.1.0 ║
|
|
║ DataConnect ║ 0.4.0 ║ 0.3.0 ║ 0.3.0 ║
|
|
╚════════════════════════════════╩═══════════╩═══════════╩═══════════╝
|
|
|
|
Last updated: 2026-03-05
|
|
Updated by: DevOps Team
|
|
Next release planning: 2026-03-08
|
|
```
|
|
|
|
---
|
|
|
|
## ⏱️ Release Timeline Template
|
|
|
|
For every release, create this timeline:
|
|
|
|
```
|
|
Release: [Product] v[Version]
|
|
Target: [date]
|
|
|
|
Milestones:
|
|
├─ Feb 28 (T-7): Code freeze
|
|
├─ Mar 1 (T-6): Staging release + QA testing
|
|
├─ Mar 5 (T-2): Final staging verification
|
|
├─ Mar 6 (T-1): Production deployment readiness
|
|
├─ Mar 7 (T-0): Production deployment 14:00-16:00 UTC
|
|
├─ Mar 8 (T+1): Monitoring & verification
|
|
└─ Mar 9 (T+2): Release celebration 🎉
|
|
|
|
Deployment Windows:
|
|
Testing: Anytime
|
|
Staging: Anytime
|
|
Prod: 14:00-16:00 UTC on release day
|
|
(Off-peak time in all timezones)
|
|
|
|
Rollback Window: 4 hours post-deployment
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Status Page Template
|
|
|
|
Share with stakeholders:
|
|
|
|
```
|
|
🚀 KROW Workforce Release Status
|
|
|
|
📅 Week of March 5, 2026
|
|
|
|
Current Production Versions:
|
|
├── Staff Mobile: 0.1.0 ✅
|
|
├── Client Mobile: 0.1.0 ✅
|
|
├── Web Dashboard: TBD ⏳
|
|
├── Command API: 0.1.0 ✅
|
|
└── Core API: 0.1.0 ✅
|
|
|
|
In Staging (Testing):
|
|
├── Staff Mobile: 0.2.0 🔄 (50% through QA)
|
|
├── Client Mobile: 0.2.0 🔄 (50% through QA)
|
|
└── Web Dashboard: 0.1.0 🔄 (30% through QA)
|
|
|
|
Next Production Release:
|
|
├── Target Date: March 15, 2026
|
|
├── Products: All 5 products
|
|
├── Focus: Shift booking, payments, mobile improvements
|
|
└── Expected Impact: 2-3 hour deployment window
|
|
|
|
Risks & Blockers: None current
|
|
|
|
Recent Incidents: None
|
|
```
|
|
|
|
---
|
|
|
|
**Document Version**: 1.0
|
|
**Created**: 2026-03-05
|
|
**Maintain**: DevOps / Release Manager
|