# 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

```bash
# 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)

```bash
# 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)
   ```yaml
   version: 1.0.0+1  # Increment build number
   ```

2. **Web Dashboard**: `apps/web/package.json`
   ```json
   "version": "1.0.0"
   ```

3. **Command API**: `backend/command-api/package.json`
   ```json
   "version": "1.0.0"
   ```

4. **Core API**: `backend/core-api/package.json`
   ```json
   "version": "1.0.0"
   ```

5. **CodeMagic**: `codemagic.yaml`
   ```yaml
   build_version: "1.0.0"
   ```

6. **CHANGELOG.md**: Add entry at top
   ```markdown
   | 2026-03-15 | 1.0.0 | Full feature v1.0.0 release [all products] |
   ```

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

#### Phase 3: Staging Release

```bash
# 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

```bash
# 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

```bash
# 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
```bash
git tag -l "staff-mobile/*" --sort=-version:refname
git tag -l "*/prod-v*" --sort=-version:refname
```

### View tag details
```bash
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
```bash
git log --oneline --decorate --tags --since="1 week ago"
```

### See all commits since last tag
```bash
git log <last-tag>..HEAD --oneline
```

### Delete a tag (if mistake)
```bash
# 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)
```bash
git tag staff-mobile/dev-v0.1.0
```

---

## 🤖 Automation Scripts (Create These)

### Create: `scripts/tag-all-products.sh`

```bash
#!/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`

```bash
#!/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:

```markdown
## 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](./RELEASE_STRATEGY.md) - Full strategy document
- [CHANGELOG.md](./CHANGELOG.md) - Version history
- [codemagic.yaml](./codemagic.yaml) - CI/CD configuration

---

**Last Updated**: 2026-03-05