Krow-workspace/RELEASE_WORKFLOW.md

Release Workflow Guide

Quick reference for executing releases in the KROW Workforce monorepo.

🚀 Quick Start Release (for a single product)

Example: Release Staff Mobile v0.2.0

# 1. Start from main branch
git checkout main
git pull origin main

# 2. Create release branch
git checkout -b release/staff-mobile-v0.2.0

# 3. Update version numbers
# File: apps/mobile/apps/staff_app/pubspec.yaml
# Change: version: 0.1.0+5 → version: 0.2.0+6

# 4. Update CHANGELOG.md
nano CHANGELOG.md
# Add entry at top:
# | 2026-03-05 | Staff Mobile 0.2.0 | [Feature/fix descriptions] |

# 5. Commit changes
git add .
git commit -m "chore(staff-mobile): bump version to 0.2.0"

# 6. Push release branch
git push origin release/staff-mobile-v0.2.0

# 7. Create pull request on GitHub
# (GitHub CLI: gh pr create --title "Release: Staff Mobile v0.2.0" --body "See RELEASE_STRATEGY.md")

# 8. Merge to main after approval
git checkout main
git pull origin main
git merge --ff-only release/staff-mobile-v0.2.0

# 9. Create git tag
git tag -a staff-mobile/dev-v0.2.0 -m "Staff Mobile v0.2.0 - [Feature description]"

# 10. Push tag
git push origin staff-mobile/dev-v0.2.0

# 11. Create GitHub Release
# - Go to Releases → Draft a new release
# - Tag: staff-mobile/dev-v0.2.0
# - Title: "Staff Mobile v0.2.0"
# - Description: Copy from CHANGELOG
# - Attach APK/AAB if available
# - Publish

---

🔄 Multi-Product Coordinated Release

Step-by-Step for v1.0.0 Release (all products)

Phase 1: Preparation (48 hours before)

# Check all tests pass
make test
make test-backend
make test-web

# Verify builds
make build-mobile-dev
make build-web

# No lint errors
make lint

Phase 2: Version Bumping

File locations to update:

1. Mobile Apps: apps/mobile/apps/staff_app/pubspec.yaml (and client_app)

   version: 1.0.0+1  # Increment build number
   

2. Web Dashboard: apps/web/package.json

   "version": "1.0.0"
   

3. Command API: backend/command-api/package.json

   "version": "1.0.0"
   

4. Core API: backend/core-api/package.json

   "version": "1.0.0"
   

5. CodeMagic: codemagic.yaml

   build_version: "1.0.0"
   

6. CHANGELOG.md: Add entry at top

   | 2026-03-15 | 1.0.0 | Full feature v1.0.0 release [all products] |
   

# Commit all version bumps
git add -A
git commit -m "chore: bump all products to v1.0.0"

Phase 3: Staging Release

# Create release branch
git checkout -b release/v1.0.0-staging

# Push and merge (or direct commit to release branch)
git push origin release/v1.0.0-staging

# Tag all products with staging
git tag -a web-dashboard/staging-v1.0.0 -m "v1.0.0 staging release"
git tag -a command-api/staging-v1.0.0 -m "v1.0.0 staging release"
git tag -a core-api/staging-v1.0.0 -m "v1.0.0 staging release"
git tag -a staff-mobile/staging-v1.0.0 -m "v1.0.0 staging release"
git tag -a client-mobile/staging-v1.0.0 -m "v1.0.0 staging release"

# Push all staging tags
git push origin --tags

# Deploy to staging environment
./scripts/deploy-staging.sh  # (create if needed)

Phase 4: QA & Testing

• Smoke test all features
• Performance tests
• Security scan
• API contract verification

Phase 5: Production Release

# Create production tags (after staging approval)
git tag -a web-dashboard/prod-v1.0.0 -m "v1.0.0 production release"
git tag -a command-api/prod-v1.0.0 -m "v1.0.0 production release"
git tag -a core-api/prod-v1.0.0 -m "v1.0.0 production release"
git tag -a staff-mobile/prod-v1.0.0 -m "v1.0.0 production release"
git tag -a client-mobile/prod-v1.0.0 -m "v1.0.0 production release"

# Push tags
git push origin --tags

# Deploy in dependency order
./scripts/deploy-prod-dataconnect.sh
./scripts/deploy-prod-backend.sh
./scripts/deploy-prod-web.sh
./scripts/deploy-prod-mobile.sh

---

🔥 Hotfix Release (Emergency Production Fix)

Example: Critical bug in Staff Mobile v1.0.0 → v1.0.1

# 1. Create hotfix branch from production tag
git checkout -b hotfix/staff-mobile-v1.0.1 staff-mobile/prod-v1.0.0

# 2. Fix the bug
git add <fixed-files>
git commit -m "fix: [critical bug description]"

# 3. Update version (PATCH bump only)
# apps/mobile/apps/staff_app/pubspec.yaml
# Change: 1.0.0+1 → 1.0.1+2

# 4. Update CHANGELOG
nano CHANGELOG.md
# Add: | 2026-03-15 | Staff Mobile 1.0.1 | Hotfix: [bug description] |

# 5. Push hotfix branch
git push origin hotfix/staff-mobile-v1.0.1

# 6. Create PR for review (expedited)
gh pr create --title "Hotfix: Staff Mobile v1.0.1" \
  --body "EMERGENCY: Critical issue fix\n\nSee CHANGELOG.md for details"

# 7. Merge to main (fast-track approval)
git checkout main
git pull origin main
git merge --ff-only hotfix/staff-mobile-v1.0.1

# 8. Tag production immediately
git tag -a staff-mobile/prod-v1.0.1 -m "Hotfix: [description]"
git push origin staff-mobile/prod-v1.0.1

# 9. Deploy to production
./scripts/deploy-prod-mobile-staff.sh

# 10. Create GitHub Release with "HOTFIX" in title

---

📊 Useful Git Commands

View all tags for a product

git tag -l "staff-mobile/*" --sort=-version:refname
git tag -l "*/prod-v*" --sort=-version:refname

View tag details

git show staff-mobile/prod-v1.0.0
git log staff-mobile/prod-v1.0.0...staff-mobile/prod-v0.9.0  # Changes between versions

List tags created in last week

git log --oneline --decorate --tags --since="1 week ago"

See all commits since last tag

git log <last-tag>..HEAD --oneline

Delete a tag (if mistake)

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

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

Create lightweight tag (simpler, no message)

git tag staff-mobile/dev-v0.1.0

---

🤖 Automation Scripts (Create These)

Create: scripts/tag-all-products.sh

#!/bin/bash
# Usage: ./scripts/tag-all-products.sh prod 1.0.0

ENV=$1  # dev, staging, prod
VERSION=$2  # e.g., 1.0.0

if [ -z "$ENV" ] || [ -z "$VERSION" ]; then
  echo "Usage: $0 <env> <version>"
  echo "Example: $0 prod 1.0.0"
  exit 1
fi

PRODUCTS=(
  "staff-mobile"
  "client-mobile"
  "web-dashboard"
  "command-api"
  "core-api"
)

for product in "${PRODUCTS[@]}"; do
  TAG="${product}/${ENV}-v${VERSION}"
  echo "Creating tag: $TAG"
  git tag -a "$TAG" -m "$product v$VERSION - $ENV release"
done

echo "Pushing all tags..."
git push origin --tags

echo "✅ All products tagged for $ENV-v$VERSION"

Create: scripts/show-version-matrix.sh

#!/bin/bash
# Show version matrix of all products

echo "📦 KROW Workforce Version Matrix"
echo "================================"
echo ""

PRODUCTS=(
  "staff-mobile"
  "client-mobile"
  "web-dashboard"
  "command-api"
  "core-api"
)

ENVS=("dev" "staging" "prod")

for env in "${ENVS[@]}"; do
  echo "=== $ENV Environment ==="
  for product in "${PRODUCTS[@]}"; do
    TAGS=$(git tag -l "${product}/${env}-v*" --sort=-version:refname | head -1)
    if [ -z "$TAGS" ]; then
      echo "  $product: (no tags)"
    else
      echo "  $product: $TAGS"
    fi
  done
  echo ""
done

---

✅ Release Checklist Template

Copy this for each release:

## Release: [Product] v[Version]

**Release Date**: [Date]
**Release Manager**: [Name]

### Pre-Release (48h before)
- [ ] All PRs merged and reviewed
- [ ] Tests passing (unit + integration)
- [ ] No lint/type errors
- [ ] Mobile builds succeed on CodeMagic
- [ ] Performance benchmarks acceptable
- [ ] Security scan passed
- [ ] CHANGELOG.md updated
- [ ] Documentation updated

### Release Day
- [ ] Create release branch: `release/[product]-v[version]`
- [ ] Bump version numbers in all files
- [ ] Commit: `chore: bump [product] to v[version]`
- [ ] Create tag: `[product]/staging-v[version]`
- [ ] Deploy to staging
- [ ] Smoke tests passed
- [ ] Create GitHub Release page

### Post-Release (24h after)
- [ ] Monitor error logs
- [ ] Verify features work end-to-end
- [ ] Create production tag (if approved)
- [ ] Deploy to production
- [ ] Final verification
- [ ] Notify users

### Rollback Plan (if needed)
- [ ] Identified issue
- [ ] Created hotfix branch
- [ ] Tagged hotfix version
- [ ] Deployed rollback
- [ ] Post-mortem created

---

🔗 Related Files

• RELEASE_STRATEGY.md - Full strategy document
• CHANGELOG.md - Version history
• codemagic.yaml - CI/CD configuration

---

Last Updated: 2026-03-05