# Release Strategy Implementation Guide

This guide walks you through implementing the tagging and release strategy for KROW Workforce.

---

## 📍 Phase 1: Initial Setup (Do This First)

### Step 1: Review and Approve Strategy

1. Read [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md)
2. Get team feedback
3. Customize if needed (adjust cadence, naming, etc.)
4. Commit to this approach

### Step 2: Verify Current State

Check current versions of all products:

```bash
# Mobile
cat apps/mobile/apps/staff_app/pubspec.yaml | grep "^version:"
cat apps/mobile/apps/client_app/pubspec.yaml | grep "^version:"

# Web
cat apps/web/package.json | grep '"version"'

# Backend
cat backend/command-api/package.json | grep '"version"'
cat backend/core-api/package.json | grep '"version"'
```

Current expected state:
```
Staff Mobile: 0.1.0+?
Client Mobile: 0.1.0+?
Web Dashboard: 0.0.0
Command API: 0.1.0
Core API: 0.1.0
```

### Step 3: Create Initial Dev Tags

Create retrospective tags for the current state. This establishes a baseline.

```bash
# Navigate to repo
cd /Users/achintha/Documents/GitHub/krow-workforce

# Create tags for current development versions
# (These mark the current checkpoint, not retrospective releases)

git tag -a staff-mobile/dev-v0.1.0 -m "Staff Mobile v0.1.0 - Initial development release"
git tag -a client-mobile/dev-v0.1.0 -m "Client Mobile v0.1.0 - Initial development release"
git tag -a web-dashboard/dev-v0.0.0 -m "Web Dashboard v0.0.0 - Pre-release"
git tag -a command-api/dev-v0.1.0 -m "Command API v0.1.0 - Initial development release"
git tag -a core-api/dev-v0.1.0 -m "Core API v0.1.0 - Initial development release"

# Push all tags to remote
git push origin --tags

# Verify tags were created
git tag -l "*" --sort=-version:refname
```

Expected output:
```
core-api/dev-v0.1.0
command-api/dev-v0.1.0
client-mobile/dev-v0.1.0
staff-mobile/dev-v0.1.0
web-dashboard/dev-v0.0.0
```

---

## 📍 Phase 2: GitHub Configuration

### Step 1: Enable Branch Protection for Production Tags

1. Go to your GitHub repo → Settings → Branches
2. Click "Add rule"
3. Configure as follows:

```
Branch name pattern: */prod-v*

Require a pull request before merging: ✅ ON
Require approvals: ✅ ON (1+ approvals)
Dismiss stale pull request approvals: ✅ ON
Require status checks to pass: ✅ ON
Require branches to be up to date before merging: ✅ ON
Include administrators: ✅ ON
Allow force pushes: ❌ OFF
Allow deletions: ❌ OFF
```

4. Click "Create"

### Step 2: Configure Required Status Checks

Status checks that must pass before merging:
- `build / test` - Unit and integration tests
- `build / lint` - Code quality checks
- `build / security-scan` - Security validation

(These should already exist from your CI/CD pipeline)

### Step 3: Setup Release Notes Template

1. Go to Settings → Releases → Set up a release
2. Add this template:

```markdown
## Release Notes: [Product] v[Version]

**Release Date**: [Date]
**Environment**: [dev/staging/prod]

### 🎯 What's New

### ✨ Features
- Feature 1
- Feature 2

### 🔧 Improvements
- Improvement 1
- Improvement 2

### 🐛 Bug Fixes
- Bug fix 1
- Bug fix 2

### 📦 Dependencies & Compatibility

**Requires:**
- Backend API v[X.X.X] or higher
- [Other dependencies]

**Compatible with:**
- [Previous version compatibility]

### 📥 Installation

[Download links and installation instructions]

### ⚠️ Known Issues & Workarounds

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

### 🔄 Migration Guide

[Steps for upgrading from previous version]

### 📞 Support

For issues: support@krow-workforce.com
```

---

## 📍 Phase 3: CI/CD Integration (CodeMagic)

### Update CodeMagic for Automated Tagging (Optional)

Edit `codemagic.yaml` to automatically create tags on successful builds:

```yaml
workflows:
  mobile-client-build:
    on:
      push:
        branches:
          - main
    # ... existing config ...
    
    # Add this section
    on_success:
      - |
        if [ "$CI_BRANCH" = "main" ]; then
          VERSION=$(grep "^version:" apps/mobile/apps/client_app/pubspec.yaml | cut -d' ' -f2)
          git tag -a client-mobile/dev-${VERSION} \
            -m "Client Mobile ${VERSION} - Development build from CodeMagic"
          git push origin client-mobile/dev-${VERSION}
        fi
```

(Optional - can be done manually initially)

---

## 📍 Phase 4: Create Release Documentation

### Copy Release Checklist Template

Create a file for release planning:

```bash
mkdir -p docs/releases
```

Create `docs/releases/RELEASE_TEMPLATE.md`:

```markdown
# Release Plan: [Product] v[Version]

**Status**: Draft / In Progress / Completed
**Target Date**: [Date]
**Release Manager**: [Name]

## Scope

[Description of features/fixes in this release]

## Pre-Release Tasks (48h before)

- [ ] All PRs merged and code reviewed
- [ ] All tests green (unit, integration, E2E)
- [ ] No lint/type errors
- [ ] Mobile builds succeed on CodeMagic
- [ ] Performance benchmarks acceptable
- [ ] Security scan passed
- [ ] CHANGELOG.md updated with all changes
- [ ] Documentation updated
- [ ] Staging environment prepared for testing

## Release Day Tasks

- [ ] Create release branch: `release/[product]-v[version]`
- [ ] Update version in all relevant files
- [ ] Commit and push release branch
- [ ] Create git tags (staging)
- [ ] Deploy to staging environment
- [ ] Run smoke tests
- [ ] Get sign-off from product owner

## Post-Release Tasks (24h after)

- [ ] Monitor error logs
- [ ] Verify all features work end-to-end
- [ ] Performance is acceptable
- [ ] Create production tags
- [ ] Deploy to production
- [ ] Final verification
- [ ] Create GitHub Release page
- [ ] Announce release to users

## Rollback Plan (if needed)

```
Issue Found: [description]
Severity: Critical / High / Medium
Action: Rollback to v[previous-version]
Hotfix: [version bump plan]
```

## Outcomes

**Release Date**: [Actual date]
**Status**: ✅ Successful / ⚠️ Issues / 🚫 Rolled back

[Additional notes]
```

---

## 📍 Phase 5: Team Training

### Create Runbook for Team

Share [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) with your team

### Conduct Training Session

**Agenda (30 minutes):**
1. Explain versioning strategy (5 min)
2. Walk through release workflow (10 min)
3. Demo: Create a test tag (10 min)
4. Q&A (5 min)

### Sample Demo Commands

```bash
# Everyone runs these to practice

# 1. See existing tags
git tag -l

# 2. Create a test tag (won't push)
git tag -a test/demo-v0.0.1 -m "Demo tag for training"

# 3. View tag details
git show test/demo-v0.0.1

# 4. Delete test tag
git tag -d test/demo-v0.0.1
```

---

## 📍 Phase 6: First Real Release

### Plan Your First Staging Release

Let's do: **Staff Mobile v0.2.0** (next development version)

### 1. Prepare Changes

```bash
# Make your feature/fix commits normally
git checkout main
git pull origin main

# Create feature branches as usual
git checkout -b feature/some-feature
# ... make changes ...
git commit -m "feat(staff-mobile): Add new feature"

git push origin feature/some-feature
# Create PR, review, merge
```

### 2. Create Release Branch

```bash
# Start release
git checkout main
git pull origin main
git checkout -b release/staff-mobile-v0.2.0
```

### 3. Bump Version

```bash
# Edit: apps/mobile/apps/staff_app/pubspec.yaml
# Change: version: 0.1.0+5 → version: 0.2.0+6

nano apps/mobile/apps/staff_app/pubspec.yaml
```

### 4. Update CHANGELOG

```bash
nano CHANGELOG.md

# Add at top:
# | 2026-03-05 | Staff Mobile 0.2.0 | Feature: [description] |
```

### 5. Commit & Tag

```bash
git add .
git commit -m "chore(staff-mobile): bump version to 0.2.0"
git push origin release/staff-mobile-v0.2.0

# Create and push tag
git tag -a staff-mobile/staging-v0.2.0 -m "Staff Mobile v0.2.0 - Staging release"
git push origin staff-mobile/staging-v0.2.0

# Verify
git tag -l "staff-mobile/*" --sort=-version:refname
```

### 6. Deploy & Test

```bash
# Deploy to staging environment
# (Use your deployment scripts or manual process)

# Run tests
make test-mobile-staff

# Get team QA approval
```

### 7. Promote to Production

```bash
# Create production tag
git tag -a staff-mobile/prod-v0.2.0 -m "Staff Mobile v0.2.0 - Production release"
git push origin staff-mobile/prod-v0.2.0

# Deploy to production
# (Use your deployment scripts)
```

### 8. Create GitHub Release

1. Go to https://github.com/[your-org]/krow-workforce/releases
2. Click "Draft a new release"
3. Fill in:
   - Tag: `staff-mobile/prod-v0.2.0`
   - Title: `Staff Mobile v0.2.0`
   - Description: Copy from CHANGELOG
   - Add APK/AAB as attachments (if available)
4. Click "Publish release"

---

## 📋 Communication Plan

### For Each Release

1. **Announcement** (release day)
   ```
   📱 Staff Mobile v0.2.0 released!
   
   Includes: [feature summary]
   Available: [iOS/Android app stores]
   ```

2. **Status Updates** (during staging QA)
   ```
   🔄 Staff Mobile v0.2.0 in staging for testing
   Expected production release: [date]
   ```

3. **Post-Release** (24h after)
   ```
   ✅ Staff Mobile v0.2.0 now in production
   All systems normal. No issues reported.
   ```

4. **If Issues**
   ```
   ⚠️ Staff Mobile v0.2.0 - Hotfix in progress
   Rollback to v0.1.0 - No impact to users
   ETA for fix: [time]
   ```

---

## 🔧 Troubleshooting

### Problem: Tag Already Exists

```bash
# If you try to create a tag that exists:
error: **/prod-v0.1.0 already exists

# Solution: Delete and recreate
git tag -d staff-mobile/dev-v0.1.0
git push origin --delete staff-mobile/dev-v0.1.0
git tag -a staff-mobile/dev-v0.1.0 -m "New message"
git push origin staff-mobile/dev-v0.1.0
```

### Problem: Can't Push Tags

```bash
# Error: remote permission denied

# Solution: Ensure you have push access
git credential-osxkeychain erase host=github.com  # Re-authenticate
# Then try again
git push origin --tags
```

### Problem: Version Not Updated Everywhere

```bash
# Verify all locations have same version
grep -r "0.2.0" apps/mobile/apps/*/pubspec.yaml
grep '"0.2.0"' apps/web/package.json
grep '"0.2.0"' backend/*/package.json
grep 'build_version: "0.2.0"' codemagic.yaml

# Update any missing locations
```

---

## ✅ Validation Checklist

After implementing this strategy, verify:

- [ ] Initial dev tags created (v0.1.0 for all products)
- [ ] GitHub branch protection configured for prod tags
- [ ] Release template documented in repo
- [ ] Team trained on release process
- [ ] CHANGELOG.md in place and tracked
- [ ] First staging release completed successfully
- [ ] GitHub Release page created for first release
- [ ] Communication plan working

---

## 🎯 Next Steps

1. ✅ Review RELEASE_STRATEGY.md with team
2. ✅ Complete Phase 1 setup (create initial tags)
3. ✅ Configure GitHub (Phase 2)
4. ⏳ First release (Staff Mobile v0.2.0) planned for [date]
5. ⏳ Establish release cadence (weekly dev, bi-weekly staging, monthly prod)

---

## 📞 Questions?

Reference documents:
- [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) - Full strategy
- [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) - Step-by-step workflows
- [CHANGELOG.md](./CHANGELOG.md) - Version history

---

**Created**: 2026-03-05
**Status**: Ready for Implementation