# 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