Krow-workspace/RELEASE_STRATEGY.md

# KROW Workforce Release Strategy & Tagging Plan

## 📋 Overview

This document establishes a systematic approach to versioning, tagging, and releasing across the KROW Workforce monorepo, which contains 5 distinct products with interdependencies.

**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/DataConnect** - Firebase Data Connect with PostgreSQL

---

## 🔗 Versioning Strategy

### Semantic Versioning (SemVer)

All products follow **Semantic Versioning 2.0.0**:
- **MAJOR.MINOR.PATCH** (e.g., `1.2.3`)
- **MAJOR**: Breaking changes, major features
- **MINOR**: Backward-compatible new features
- **PATCH**: Bug fixes, minor improvements

### Version Independence

Each product maintains its own version:
- Products can release independently
- No requirement for synchronized versions across products
- Allows flexibility in release schedules

### Current Baseline (as of 2026-03-05)

| Product | Current Version | Status |
|---------|-----------------|--------|
| Staff Mobile App | 0.1.0 | Development |
| Client Mobile App | 0.1.0 | Development |
| Web Dashboard | 0.0.0 | Pre-release |
| Backend (Command API) | 0.1.0 | Development |
| Backend (Core API) | 0.1.0 | Development |
| DataConnect | N/A | Schema-driven |

---

## 🏷️ Git Tag Naming Convention

### Format

```
<product>/<environment>-v<version>
```

### Products
- `staff-mobile` - Staff mobile application
- `client-mobile` - Client mobile application
- `web-dashboard` - Web dashboard
- `command-api` - Backend command API
- `core-api` - Backend core API
- `dataconnect` - Database/DataConnect schema

### Environments
- `dev` - Development release (unstable, for testing)
- `staging` - Staging release (pre-production)
- `prod` - Production release (stable, customer-facing)

### Examples
```
staff-mobile/dev-v0.1.0
client-mobile/staging-v0.1.0
web-dashboard/prod-v1.0.0
command-api/dev-v0.2.1
dataconnect/prod-v0.3.0
```

### Release Candidate Suffix (Optional)
For pre-release versions:
```
staff-mobile/staging-v0.1.0-rc.1
web-dashboard/prod-v1.0.0-rc.2
```

---

## 📅 Release Cadence

### Development Releases (`dev`)
- **Frequency**: Weekly or as-needed
- **Trigger**: Completed feature branches, bug fixes
- **Duration**: Not stable, for internal testing
- **Deployment**: Dev environment only

### Staging Releases (`staging`)
- **Frequency**: Bi-weekly
- **Trigger**: Completion of sprint/feature milestone
- **Duration**: Should maintain stability for 1-2 weeks
- **Deployment**: Staging environment for QA

### Production Releases (`prod`)
- **Frequency**: Monthly or sprint-based (typically end of month)
- **Trigger**: Successful staging validation + product sign-off
- **Duration**: Maintain for 2+ months
- **Deployment**: Production environment for customers

---

## 🔄 Release Dependency Order

### Critical Path (Recommended)

**For synchronized releases:**

1. **DataConnect Schema** (if schema changes) - Deploy first
2. **Backend Services** (Command API → Core API)
3. **Web Dashboard**
4. **Mobile Apps** (Staff first, then Client)

**Rationale:**
- DataConnect schema changes must be deployed before APIs consume new fields
- Backend APIs must be stable before frontend depends on new endpoints
- Web can be deployed independently but should test against new backend
- Mobile apps can be released independently but won't have full features until matching backend is live

### Independent Releases

Products can release independently if they don't introduce breaking changes:
- Mobile apps can release without backend changes
- Web dashboard can release bug fixes independently
- Backend can release non-breaking API changes independently

---

## 📦 Release Checklist

### Pre-Release (48 hours before)

- [ ] Code review complete on all changes
- [ ] All tests passing (unit, integration, E2E)
- [ ] Mobile app builds succeed on CodeMagic
- [ ] No lint/type errors
- [ ] Performance benchmarks acceptable
- [ ] Security scan completed
- [ ] Documentation updated
- [ ] CHANGELOG.md updated with changes

### Release Day

- [ ] Create release branch from main: `release/v<version>`
- [ ] Update version numbers in all relevant files:
  - Mobile: `pubspec.yaml` version + build number
  - Web: `package.json` version
  - Backend: `package.json` version
  - Backend: Update `codemagic.yaml` version refs
- [ ] Create git tag with appropriate name
- [ ] Merge release branch back to main
- [ ] Deploy to target environment
- [ ] Smoke tests run successfully
- [ ] Create GitHub Release with:
  - Release notes from CHANGELOG
  - Build artifacts (APK/AAB for mobile)
  - Deployment checklist items
  - Known issues

### Post-Release

- [ ] Verify in target environment (staging → prod)
- [ ] Monitor error logs for 24 hours
- [ ] Notify users of deployment
- [ ] Update status page if applicable
- [ ] Tag next development version as beginning

---

## 🔐 Protected Tags

### Rules

- **Production tags (`prod-v*`)**: Require pull request review
- **Staging tags (`staging-v*`)**: Require at least 1 approval
- **Dev tags (`dev-v*`)**: No restrictions

### Implementation in GitHub

1. Go to Repo Settings → Branches → Add rule
2. Apply to tag name pattern: `**/prod-v*`
3. Require pull request reviews before merging
4. Require status checks to pass

---

## 📝 Version File Locations

### Mobile Apps (Staff & Client)

**File**: `/apps/mobile/apps/staff_app/pubspec.yaml` (and client_app)
```yaml
version: 0.1.0+1
```
- First number = version
- After `+` = build number (increment for each release)

### Web Dashboard

**File**: `/apps/web/package.json`
```json
{
  "version": "0.0.0"
}
```

### Backend Services

**Files**: 
- `/backend/command-api/package.json`
- `/backend/core-api/package.json`

```json
{
  "version": "0.1.0"
}
```

### CodeMagic Configuration

**File**: `/codemagic.yaml`
```yaml
workflows:
  mobile-client-build:
    environment:
      flutter: stable
    settings:
      build_version: "0.1.0" # Update this
```

---

## 📊 Release Timeline Example: v1.0.0

**Timeline for coordinated production release:**

```
Day 1 (Monday)
├─ Code freeze announced
├─ All feature branches merged to main
└─ QA begins testing

Day 6 (Saturday)
├─ All tests pass
├─ Release manager creates release/v1.0.0 branch
└─ Version numbers bumped to 1.0.0 everywhere

Day 7 (Sunday)
├─ Tags created:
│  ├─ web-dashboard/staging-v1.0.0
│  ├─ command-api/staging-v1.0.0
│  ├─ core-api/staging-v1.0.0
│  ├─ staff-mobile/staging-v1.0.0
│  ├─ client-mobile/staging-v1.0.0
│  └─ dataconnect/staging-v1.0.0 (if schema changes)
├─ Deploy to staging environment
├─ QA smoke tests
└─ Product owner sign-off

Day 13 (Saturday) - Production Release
├─ Create production tags:
│  ├─ web-dashboard/prod-v1.0.0
│  ├─ command-api/prod-v1.0.0
│  └─ [other products]
├─ Deploy to production (following dependency order)
├─ Verify in production
└─ Release GitHub Release page
```

---

## 🛠️ Git Commands

### Create a Tag

```bash
# Create annotated tag
git tag -a staff-mobile/dev-v0.1.0 -m "Staff mobile v0.1.0 - [feature description]"

# Push tag to remote
git push origin staff-mobile/dev-v0.1.0

# Or push all tags
git push origin --tags
```

### List Tags for a Product

```bash
# Show all staff-mobile tags
git tag -l "staff-mobile/*" --sort=-version:refname

# Show tags in specific environment
git tag -l "*/prod-v*"
```

### Delete a Tag

```bash
# Local deletion
git tag -d staff-mobile/dev-v0.1.0

# Remote deletion
git push origin --delete staff-mobile/dev-v0.1.0
```

---

## 🔍 Rollback Procedures

### If Critical Issue Found in Prod

1. **Identify**: Determine which product caused the issue
2. **Revert**: 
   ```bash
   git revert <commit-hash> -m 1
   git push origin main
   ```
3. **Tag**: Create hotfix tag
   ```bash
   git tag -a staff-mobile/prod-v0.1.1 -m "Hotfix: [issue description]"
   git push origin staff-mobile/prod-v0.1.1
   ```
4. **Deploy**: Follow deployment checklist
5. **Communication**: Notify users and stakeholders

### If Staging Issue Found

Similar to rollback but to staging environment. No customer impact.

---

## 📋 Release Notes Template

Create a GitHub Release with the following:

```markdown
# Staff Mobile v0.1.0 Release

**Release Date**: 2026-03-15

## What's New

### Features
- [ ] Feature 1 description
- [ ] Feature 2 description

### Improvements
- [ ] Improvement 1 description

### Bug Fixes
- [ ] Bug fix 1 description

## Dependencies

- ✅ Requires Backend API v0.1.0 or higher
- ✅ Requires DataConnect schema v0.3.0 or higher

## Installation

[iOS/Android download links]

## Known Issues

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

## Migration Guide (if needed)

Steps for users to migrate from previous version.

## Support

For issues, contact support@krow-workforce.com or [GitHub Issues Link]
```

---

## 📊 Monitoring & Metrics

### Track Per Release

- [ ] Time to release
- [ ] Number of bugs in production
- [ ] User adoption rate
- [ ] Performance changes
- [ ] Rollback rate
- [ ] Deploy success rate

### Dashboard

Consider setting up a tool to track:
- Deploy frequency
- Lead time for changes
- Mean time to recovery (MTTR)
- Change failure rate

---

## 🔗 Related Documents

- [CHANGELOG.md](./CHANGELOG.md) - Historical version logs
- [docs/01-backend-api-specification.md](./docs/01-backend-api-specification.md) - API contract
- [docs/ARCHITECTURE/system-bible.md](./docs/ARCHITECTURE/system-bible.md) - System design
- [codemagic.yaml](./codemagic.yaml) - CI/CD pipeline

---

## ✅ Next Steps

1. **Approve this strategy** with the team
2. **Configure GitHub branch protection** for tag patterns
3. **Set up release automation** in CI/CD (GitHub Actions or CodeMagic)
4. **Create the v1.0.0 milestone** with all planned features
5. **Establish communication cadence** for releases (weekly status, release announcements)
6. **Train team members** on release process

---

**Last Updated**: 2026-03-05
**Owner**: DevOps/Release Engineering
**Status**: ✅ Active