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.
17 KiB
17 KiB
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