Krow-workspace/RELEASE_IMPLEMENTATION.md

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

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

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

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

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:

mkdir -p docs/releases

Create docs/releases/RELEASE_TEMPLATE.md:

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

# 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

# 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

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

3. Bump Version

# 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

nano CHANGELOG.md

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

5. Commit & Tag

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

# 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

# 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

# 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

# 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

# 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 - Full strategy
• RELEASE_WORKFLOW.md - Step-by-step workflows
• CHANGELOG.md - Version history

---

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