# 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 ``` /-v.. ``` ### 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 ```markdown | 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 /-v -m "Release message"` - [ ] Push tags: `git push origin ` - [ ] 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: ```bash # Revert commit git revert -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 ```bash # 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 ```markdown # 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](./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](./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_RELEASE_PLAN.md) - Mobile app releases - [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) - Emergency procedures - [../../RELEASE_STRATEGY.md](../../RELEASE_STRATEGY.md) - Original detailed guide - [../../CHANGELOG.md](../../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](./MOBILE_RELEASE_PLAN.md) for app-specific process.