Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add comprehensive release process documentation and version file references

Browse Source 
- 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.
This commit is contained in:
Achintha Isuru
2026-03-05 10:49:09 -05:00
parent faae6c07d5
commit 085445e730
13 changed files with 4650 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

564
docs/RELEASE/MOBILE_RELEASE_PLAN.md Normal file
View File

@@ -0,0 +1,564 @@
# 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