Krow-workspace/docs/RELEASE/OVERALL_RELEASE_PLAN.md

KROW Workforce - Overall Release Plan

Document Version: 1.0
Created: 2026-03-05
Last Updated: 2026-03-05
Product Scope: All products (Mobile, Web, Backend, Database)

---

📋 Overview

This document outlines the release strategy for KROW Workforce monorepo containing 5 products:

1. Staff Mobile App (Flutter - iOS/Android)
2. Client Mobile App (Flutter - iOS/Android)
3. Web Dashboard (React/Vite)
4. Backend Services (Node.js - Command API, Core API)
5. Database (Firebase Data Connect with PostgreSQL)

---

🔗 Versioning Strategy

Semantic Versioning (SemVer)

All products use Semantic Versioning 2.0.0:

MAJOR.MINOR.PATCH-QUALIFIER
0.1.0
1.2.3-rc.1

• MAJOR (0→1): Breaking changes, major features
• MINOR (1→2): Backward-compatible new features
• PATCH (3→4): Bug fixes, minor improvements
• QUALIFIER (optional): -rc.1, -beta.1, -hotfix.1

Version Independence

Each product maintains independent versioning:

• Products release on their own schedule
• No requirement to synchronize versions
• Can release major updates independently

---

🏷️ Git Tag Naming Convention

Standard Format

<product>/<environment>-v<major>.<minor>.<patch>

Products & Environments

Product	Tag Prefix	Environments
Staff Mobile	krow-withus-worker-mobile	dev, stage, prod
Client Mobile	krow-withus-client-mobile	dev, stage, prod
Web Dashboard	web-dashboard	dev, stage, prod
Command API	command-api	dev, stage, prod
Core API	core-api	dev, stage, prod
DataConnect	dataconnect	stage, prod

Environments

• dev: Development releases (daily/weekly), unstable
• stage: Staging releases (bi-weekly), pre-production testing
• prod: Production releases (monthly), stable, customer-facing

Examples

krow-withus-worker-mobile/dev-v0.1.0
krow-withus-client-mobile/stage-v0.2.0
web-dashboard/prod-v1.0.0
command-api/dev-v0.2.1
core-api/prod-v0.1.0

---

📅 Release Cadence

Development Releases (dev)

• Frequency: Weekly or as-needed
• Scope: Feature completions, bug fixes
• Duration: Not guaranteed stable
• Deployment: Dev environment only
• Who: Development team

Staging Releases (stage)

• Frequency: Bi-weekly (typically mid/end of sprint)
• Scope: Sprint completion, feature milestones
• Duration: 1-2 weeks stability expected
• Deployment: Staging environment for QA
• Who: QA team validates

Production Releases (prod)

• Frequency: Monthly or sprint-based
• Scope: Feature milestone completion, critical fixes
• Duration: 4+ weeks standard support
• Deployment: Production environment (customer-facing)
• Who: Product owner approves, DevOps deploys

---

🔄 Product Dependency & Deployment Order

Critical Path (for synchronized releases)

Deploy in this order:

1. DataConnect Schema (if schema changed)

   • Deploy schema changes first
   • All APIs depend on schema availability

2. Backend Services (parallel OK)

   • Command API
   • Core API
   • Both can deploy simultaneously

3. Web Dashboard

   • Can deploy once backend ready
   • Test API endpoints stable

4. Mobile Apps (parallel OK)

   • Staff Mobile
   • Client Mobile
   • Both can deploy simultaneously, independent of web

Independent Releases

Products can release independently if:

• No backend schema changes
• No breaking API changes
• No data migrations required

Example: Staff Mobile can release UI improvements without web/backend changes.

---

📝 CHANGELOG Management

Location & Structure

Each major product maintains its own CHANGELOG:

apps/mobile/packages/features/staff/*/CHANGELOG.md
apps/mobile/packages/features/client/*/CHANGELOG.md
apps/web/CHANGELOG.md
backend/command-api/CHANGELOG.md
backend/core-api/CHANGELOG.md
CHANGELOG.md (root - high-level overview)

Format

| Date | Version | Change |
|------|---------|--------|
| 2026-03-05 | 0.1.0 | Initial release - [feature list] |

What to Track

• Features added
• Bugs fixed
• Breaking changes (clearly marked ⚠️)
• Dependencies upgraded
• Migration steps (if applicable)

---

✅ Release Checklist

Pre-Release (48 hours before)

• All PRs merged to main
• Code review complete
• All tests passing (unit, integration, E2E)
• No lint/type errors
• Mobile builds succeed (CodeMagic)
• Performance benchmarks acceptable
• Security scan completed
• CHANGELOG.md updated with all changes
• Documentation updated
• Team notified of pending release

Release Day

• Update version numbers in all relevant files
• Update CHANGELOG with date
• Git commit: git commit -m "chore: bump version to X.Y.Z"
• Git push changes to main
• Create git tag: git tag -a <product>/<env>-v<version> -m "Release message"
• Push tags: git push origin <tag-name>
• Deploy to target environment
• Smoke tests pass
• Create GitHub Release page
• Notify stakeholders

Post-Release (24 hours)

• Monitor error logs
• Verify all features work end-to-end
• Performance is acceptable
• No regressions reported
• Users updated if needed
• Document any issues

---

🔐 Protected Tags

Branch Protection Rules

Production tags require approval:

• Tag pattern: */prod-v*
• Require pull request review (1+ approval)
• Require status checks to pass
• Prevent force pushes
• Disable deletions

Staging tags recommended:

• Tag pattern: */stage-v*
• Consider: Require at least 1 approval
• Status checks should pass

Dev tags open:

• Tag pattern: */dev-v*
• No restrictions
• Allow fast iteration

---

🚨 Rollback Procedures

For Production Issues

If critical issue detected:

1. Identify the product and issue
2. Assess impact and severity
3. Decide rollback vs hotfix
   • Rollback: Undo entire release
   • Hotfix: Fix and re-release (see HOTFIX_PROCESS.md)
4. Execute rollback:

   # Revert commit
   git revert <commit-hash> -m 1
   git push origin main
   
   # Or switch traffic back to previous version
   # (depends on deployment infrastructure)
   

5. Communicate with users
6. Plan hotfix or next release

Time Windows

• Awareness: 15-30 minutes (monitoring)
• Decision: 15-30 minutes (severity assessment)
• Execution: 15-60 minutes (rollback deployment)
• Verification: 30-60 minutes (smoke tests)
• Communication: Immediate + 24h updates

Total: 2-4 hours from detection to stable state

---

📊 Release Templates & Tools

Git Commands

# Create tag
git tag -a krow-withus-worker-mobile/dev-v0.1.0 \
  -m "Staff Mobile v0.1.0 - Feature X"

# Push tag
git push origin krow-withus-worker-mobile/dev-v0.1.0

# View tags for product
git tag -l "krow-withus-worker-mobile/*" --sort=-version:refname

# See what's in a tag
git show krow-withus-worker-mobile/dev-v0.1.0

# Delete tag (if mistake)
git tag -d krow-withus-worker-mobile/dev-v0.1.0
git push origin --delete krow-withus-worker-mobile/dev-v0.1.0

GitHub Release Template

# Krow With Us - Worker Mobile - DEV - v0.1.0

**Release Date**: [Date]
**Environment**: Development

## What's New

### ✨ Features
- Feature 1 description
- Feature 2 description

### 🔧 Improvements
- Improvement 1
- Improvement 2

### 🐛 Bug Fixes
- Bug fix 1
- Bug fix 2

## Dependencies

Requires:
- Backend API v0.1.0 or higher
- DataConnect schema v0.3.0 (if updated)

## Installation

[Download links & instructions]

## Known Issues

- Issue 1: [desc] (Workaround: ...)

## Support

contact: support@krow-workforce.com

---

🔄 Hotfix Releases

See HOTFIX_PROCESS.md for emergency procedures.

Quick summary:

1. Branch from production tag
2. Fix the issue
3. Bump PATCH version only
4. Test and deploy immediately
5. Create hotfix tag

---

📱 Mobile-Specific Release Process

See MOBILE_RELEASE_PLAN.md for detailed mobile app process including:

• Staff Mobile vs Client Mobile differences
• Build number management
• CodeMagic integration
• App store distribution
• CHANGELOG per app

---

🎯 Release Coordination

Single Product Release

1. Update version files
2. Update CHANGELOG
3. Commit & push
4. Create tag
5. Deploy
6. Create GitHub Release

Time: 30-45 minutes (excluding testing)

Multi-Product Release (e.g., v1.0.0)

Pre-release phase (1 week before):

• Code freeze announced
• QA testing begins
• No new features merged

Release phase (2-3 days):

• Staging release (all products)
• QA validation
• Product owner sign-off

Production phase (1 day):

• Deploy in dependency order
• Smoke tests each product
• Monitor 24 hours
• User communication

Time: 5-7 days total, 4 hours active deployment

---

📞 Roles & Responsibilities

Role	Responsibility
Developer	Keep code release-ready, update versions
QA	Test staging releases, validate prod
Release Engineer	Create tags, manage deployment, monitor
Product Owner	Approve releases, communicate timeline
DevOps	Infrastructure ready, deployment scripts

---

📊 Success Metrics

Track these per release:

• Lead Time: Time from code commit to production
• Deployment Frequency: How often you release
• Change Failure Rate: % of releases needing rollback
• Time to Recovery: Time to fix production issues
• User Adoption: % of users on latest version

---

📚 Related Documentation

• MOBILE_RELEASE_PLAN.md - Mobile app releases
• HOTFIX_PROCESS.md - Emergency procedures
• ../../RELEASE_STRATEGY.md - Original detailed guide
• ../../CHANGELOG.md - Root version history

---

✅ Implementation Status

• ✅ Versioning strategy: SemVer
• ✅ Environments: dev, stage, prod
• ✅ Tag naming: Product-specific with brand prefix
• ✅ Product dependencies: Defined
• ✅ Release cadence: 3 levels
• ⏳ GitHub Actions: To be set up
• ⏳ Deployment automation: To be set up

---

Next Step: Review MOBILE_RELEASE_PLAN.md for app-specific process.