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.
453 lines
10 KiB
Markdown
453 lines
10 KiB
Markdown
# 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
|
|
|
|
```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 <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:
|
|
```bash
|
|
# 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
|
|
|
|
```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.
|
|
|