feat: add comprehensive release process documentation and version file references
- 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.
This commit is contained in:
Achintha Isuru
382
RELEASE_VISUAL_GUIDE.md
Normal file
382
RELEASE_VISUAL_GUIDE.md
Normal file
@@ -0,0 +1,382 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user