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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```bash
# 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](./OVERALL_RELEASE_PLAN.md) - General strategy
- [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) - Emergency procedures
- [../../CHANGELOG.md](../../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