# 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.

