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)

version: 0.1.0+1

• First number = version
• After + = build number (increment for each release)

Web Dashboard

File: /apps/web/package.json

{
  "version": "0.0.0"
}

Backend Services

Files:

• /backend/command-api/package.json
• /backend/core-api/package.json

{
  "version": "0.1.0"
}

CodeMagic Configuration

File: /codemagic.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

# 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

# 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

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

   git revert <commit-hash> -m 1
   git push origin main
   

3. Tag: Create hotfix tag

   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:

# 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 - Historical version logs
• docs/01-backend-api-specification.md - API contract
• docs/ARCHITECTURE/system-bible.md - System design
• 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