085445e730
- Introduced RELEASE_VISUAL_GUIDE.md for a visual overview of the release pipeline, including development, staging, and production phases. - Created RELEASE_WORKFLOW.md detailing step-by-step release procedures for single and multi-product releases, including hotfix processes. - Added VERSION_FILES_REFERENCE.md to outline all necessary version file updates for each product during releases, ensuring consistency and completeness.
565 lines
11 KiB
Markdown
565 lines
11 KiB
Markdown
# 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
|