Krow-workspace/docs/RELEASE/MOBILE_RELEASE_PLAN.md

Mobile App Release Plan

For Staff Mobile & Client Mobile Apps

---

📱 Overview

This document covers release procedures for:

• Staff Mobile App (aka "Worker Mobile") - krow-withus-worker-mobile
• Client Mobile App - krow-withus-client-mobile

Both apps:

• Built with Flutter
• Distributed to iOS & Android app stores
• Maintain independent versions
• Have independent CHANGELOGs
• Share backend infrastructure

---

🏷️ Tag & Release Naming

Tag Format

krow-withus-<app>-mobile/<environment>-v<major>.<minor>.<patch>

Examples

Staff Mobile (Worker Mobile)

krow-withus-worker-mobile/dev-v0.1.0
krow-withus-worker-mobile/stage-v0.2.0
krow-withus-worker-mobile/prod-v1.0.0
krow-withus-worker-mobile/prod-v1.0.1-hotfix.1

Client Mobile

krow-withus-client-mobile/dev-v0.1.0
krow-withus-client-mobile/stage-v0.2.0
krow-withus-client-mobile/prod-v1.0.0

GitHub Release Names

Krow With Us - Worker Mobile - DEV - v0.1.0
Krow With Us - Worker Mobile - STAGE - v0.2.0
Krow With Us - Worker Mobile - PROD - v1.0.0

Krow With Us - Client Mobile - DEV - v0.1.0
Krow With Us - Client Mobile - STAGE - v0.2.0
Krow With Us - Client Mobile - PROD - v1.0.0

---

📝 CHANGELOG Management

Location

Each app has its own CHANGELOG in the apps/mobile/ directory structure:

apps/mobile/
├── packages/
│   ├── features/
│   │   ├── staff/
│   │   │   ├── authentication/CHANGELOG.md
│   │   │   ├── home/CHANGELOG.md
│   │   │   ├── payments/CHANGELOG.md
│   │   │   ├── shifts/CHANGELOG.md
│   │   │   └── ... (other staff features)
│   │   └── client/
│   │       ├── dashboard/CHANGELOG.md
│   │       ├── orders/CHANGELOG.md
│   │       └── ... (other client features)
│   └── ... (other packages)
├── apps/
│   ├── staff_app/CHANGELOG.md              ← Staff app root
│   └── client_app/CHANGELOG.md             ← Client app root
└── CHANGELOG.md                            ← Consolidated (optional)

App-Level CHANGELOG Format

File: apps/mobile/apps/staff_app/CHANGELOG.md

# Staff Mobile App - Change Log

## [0.2.0] - 2026-03-15

### Added
- Feature X implementation
- Feature Y enhancement
- New UI component Z

### Fixed
- Bug fix for issue #123
- Crash when loading payments

### Changed
- Updated design system
- Improved performance

### Deprecated
- Removed old API endpoint

## [0.1.0] - 2026-03-01

### Added
- Initial release
- Authentication with phone & OTP
- Shift browsing and booking
- Clock in/out functionality
- Payment history view

Consolidated CHANGELOG (Optional)

File: apps/mobile/CHANGELOG.md (at root of mobile folder)

High-level overview of both apps:

# Krow Workforce - Mobile Apps - Change Log

## Staff Mobile v0.2.0 + Client Mobile v0.1.0 - 2026-03-15

### Staff Mobile v0.2.0
- Feature improvements
- Bug fixes

### Client Mobile v0.1.0
- Initial release

## Previous versions...

---

📝 Version Files

Staff Mobile App

Primary Version File: apps/mobile/apps/staff_app/pubspec.yaml

name: staff_app
description: "Krow With Us - Staff App"

# Version format: MAJOR.MINOR.PATCH+BUILD_NUMBER
version: 0.1.0+1

environment:
  sdk: '>=3.10.0 <4.0.0'
  flutter: '>=3.38.0 <4.0.0'

Rules:

• Update version before each release
• Bump build number (+1) every build
• SemVer only for version part (before +)

Client Mobile App

Primary Version File: apps/mobile/apps/client_app/pubspec.yaml

name: client_app
description: "Krow With Us - Client App"

version: 0.1.0+1

environment:
  sdk: '>=3.10.0 <4.0.0'
  flutter: '>=3.38.0 <4.0.0'

---

🚀 Release Workflow

Step 1: Create Release Branch

cd /Users/achintha/Documents/GitHub/krow-workforce

# For Staff Mobile
git checkout -b release/staff-mobile-v0.2.0

# For Client Mobile
git checkout -b release/client-mobile-v0.2.0

---

Step 2: Update Version Numbers

Staff Mobile Example (v0.1.0 → v0.2.0)

File: apps/mobile/apps/staff_app/pubspec.yaml

# Old
version: 0.1.0+5

# New
version: 0.2.0+6

Client Mobile Example (v0.1.0 → v0.2.0)

File: apps/mobile/apps/client_app/pubspec.yaml

# Old
version: 0.1.0+3

# New
version: 0.2.0+4

---

Step 3: Update CHANGELOG

File: apps/mobile/apps/staff_app/CHANGELOG.md

Add entry at top:

# Staff Mobile App - Change Log

## [0.2.0] - 2026-03-05

### Added
- New shift details page with profile gating
- Benefits overview section
- Auto-match functionality

### Fixed
- Payment history display bug
- Clock-in location verification

### Changed
- Updated design system components
- Improved shift booking flow

## [0.1.0] - 2026-02-15
...

---

Step 4: Commit Changes

cd /Users/achintha/Documents/GitHub/krow-workforce

# Stage changes
git add apps/mobile/apps/staff_app/pubspec.yaml
git add apps/mobile/apps/staff_app/CHANGELOG.md

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

- Updated pubspec.yaml version: 0.1.0 → 0.2.0
- Updated build number: 5 → 6
- Updated CHANGELOG.md with v0.2.0 changes"

---

Step 5: Create Pull Request

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

# Create PR (GitHub CLI)
gh pr create \
  --title "Release: Staff Mobile v0.2.0" \
  --body "## Release: Staff Mobile v0.2.0

### Changes
- See CHANGELOG.md for full list

### Testing
- [ ] All tests passing
- [ ] Manual testing complete
- [ ] CodeMagic build successful

### Checklist
- [x] Version updated
- [x] CHANGELOG updated
- [x] Branch created from main
- [ ] Approved by team lead"

---

Step 6: Merge to Main

Once PR is approved:

# Switch to main
git checkout main
git pull origin main

# Merge (fast-forward only)
git merge --ff-only release/staff-mobile-v0.2.0

# Push to remote
git push origin main

# Delete release branch
git push origin --delete release/staff-mobile-v0.2.0

---

Step 7: Create Git Tag

# For DEV release
git tag -a krow-withus-worker-mobile/dev-v0.2.0 \
  -m "Staff Mobile v0.2.0 - Dev Release

Features:
- Shift details improvements
- Benefits overview
- Auto-match functionality

Testing:
- All unit tests passing
- Manual QA on dev environment"

# For STAGE release
git tag -a krow-withus-worker-mobile/stage-v0.2.0 \
  -m "Staff Mobile v0.2.0 - Stage Release"

# For PROD release
git tag -a krow-withus-worker-mobile/prod-v0.2.0 \
  -m "Staff Mobile v0.2.0 - Production Release"

Push tags:

git push origin krow-withus-worker-mobile/dev-v0.2.0
git push origin krow-withus-worker-mobile/stage-v0.2.0
git push origin krow-withus-worker-mobile/prod-v0.2.0

---

Step 8: Create GitHub Release

1. Go to: GitHub → Releases → Draft a new release
2. Fill in:

Tag version: krow-withus-worker-mobile/dev-v0.2.0

Release title:
Krow With Us - Worker Mobile - DEV - v0.2.0

Description:

## 🎯 What's New in v0.2.0

### ✨ Features
- Shift details page with profile completion gating
- Benefits overview with sick leave tracking
- Auto-match shift recommendations

### 🔧 Improvements
- Faster payment history loading
- Better shift booking UX
- Improved clock-in reliability

### 🐛 Bug Fixes
- Fixed payment display date issue
- Fixed location verification on iOS 15+
- Fixed crash when no shifts available

## 📦 Installation

**iOS**: Download via TestFlight (internal) or App Store
**Android**: Download via Play Store

## 🔗 Dependencies

Requires:
- Backend API v0.1.0+
- DataConnect schema v0.3.0+

## ⚠️ Known Issues

- Location permissions take 5-10 seconds on first install
- Workaround: Grant permissions in Settings app

## 📝 Notes for QA

- Test on actual device, not emulator
- Verify clock-in with GPS enabled
- Test all payment history edge cases

---

Release Date: 2026-03-05
Build Number: 6

3. Optional: Attach build artifacts (APK/AAB from CodeMagic)
4. Click: "Publish release"

---

🔄 Deployment Flow

Dev Release → Staging

After dev is tested:

# Create stage tag from same commit
git tag -a krow-withus-worker-mobile/stage-v0.2.0 \
  krow-withus-worker-mobile/dev-v0.2.0 \
  -m "Staff Mobile v0.2.0 - Stage Release"

git push origin krow-withus-worker-mobile/stage-v0.2.0

# Deploy using CodeMagic or manual process

Staging Release → Production

After QA approval:

# Create prod tag from same commit
git tag -a krow-withus-worker-mobile/prod-v0.2.0 \
  krow-withus-worker-mobile/stage-v0.2.0 \
  -m "Worker Mobile v0.2.0 - Production Release"

git push origin krow-withus-worker-mobile/prod-v0.2.0

# Deploy to production

---

📱 App Store Distribution

iOS App Store

Version Name: Match pubspec.yaml version (0.2.0)
Build Number: Match pubspec.yaml build number (+6)

Steps:

1. Ensure TestFlight build passed
2. Submit to App Review
3. Apple reviews (3-5 days)
4. Release to users (can be phased)

Google Play Store

Version Name: Match pubspec.yaml version (0.2.0)
Version Code: Match pubspec.yaml build number (6)

Steps:

1. Upload APK/AAB from CodeMagic
2. Fill in release notes (from CHANGELOG)
3. Submit for review
4. Google reviews (hours to 24h)
5. Release to users (can be phased, e.g., 10% then 100%)

---

🔧 Pre-Release Checklist

Before creating tags:

• All PRs merged to main
• Code review complete
• Tests passing (unit, widget, integration)
• No lint/analysis errors: flutter analyze
• Pubspec.yaml version updated
• Build number incremented
• CHANGELOG.md updated with date
• Screenshots prepared (fresh)
• Release notes drafted
• No hardcoded strings (use translations)
• No debug prints remaining
• Performance acceptable (app launch < 3 seconds)
• Screen lock/unlock works
• Deep links tested
• Notifications working
• GPS/location working
• Camera permissions working
• All user-facing text reviewed

---

🎯 Release Cadence

Development Releases (dev)

• Frequency: Weekly
• Day: Monday 10:00 UTC
• Process: Quick, test in dev only

Staging Releases (stage)

• Frequency: Bi-weekly (on sprint/feature completion)
• Day: Wednesday before production
• Process: Full QA testing, 1 week in staging

Production Releases (prod)

• Frequency: Monthly (end of sprint)
• Day: Sunday/Monday morning (low traffic)
• Process: Full validation, market distribution

---

🔗 Related

• OVERALL_RELEASE_PLAN.md - General strategy
• HOTFIX_PROCESS.md - Emergency procedures
• ../../CHANGELOG.md - Root-level history

---

📞 Common Questions

Q: What if I need to release just one app (not both)? A: Completely fine! Each app is independent. Release when ready.

Q: Do I need to update the root CHANGELOG? A: Optional. If you do, keep it high-level and reference app-specific CHANGELOGs.

Q: What about shared packages inside mobile/? A: If shared package updated, mention in both app CHANGELOGs.

Q: How do I handle breaking changes? A: MAJOR version bump (0.x → 1.x) and clearly document in CHANGELOG.

Q: Can I release dev and stage on different days? A: Yes, no fixed schedule for dev/stage. Prod should be consistent (Sundays).

---

Last Updated: 2026-03-05
Owner: Mobile Engineering Team
Status: Active