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

chore: remove overall release plan document and add mobile app release process documentation

Browse Source
This commit is contained in:
Achintha Isuru
2026-03-06 15:26:08 -05:00
parent 6feeea920b
commit 37d8427df9
11 changed files with 818 additions and 2141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/MOBILE/00-agent-development-rules.md
View File

@@ -92,7 +92,7 @@ You have access to `prototypes/` folders. When migrating code:
1. **Extract Assets**:
* You MAY copy icons, images, and colors. But they should be tailored to the current design system. Do not change the colours and typgorahys in the design system. They are final. And you have to use these in the UI.
* When you matching colous and typography, from the POC match it with the design system and use the colors and typography from the design system. As mentioned in the `apps/mobile/docs/03-design-system-usage.md`.
* When you matching colous and typography, from the POC match it with the design system and use the colors and typography from the design system. As mentioned in the `apps/mobile/docs/02-design-system-usage.md`.
2. **Extract Layouts**: You MAY copy `build` methods for UI structure.
3. **REJECT Architecture**: You MUST **NOT** copy the `GetX`, `Provider`, or `MVC` patterns often found in prototypes. Refactor immediately to **Bloc + Clean Architecture with Flutter Modular and Melos**.
@@ -103,7 +103,7 @@ If a user request is vague:
1. **STOP**: Do not guess domain fields or workflows.
2. **ANALYZE**:
- For architecture related questions, refer to `apps/mobile/docs/01-architecture-principles.md` or existing code.
- For design system related questions, refer to `apps/mobile/docs/03-design-system-usage.md` or existing code.
- For design system related questions, refer to `apps/mobile/docs/02-design-system-usage.md` or existing code.
3. **DOCUMENT**: If you must make an assumption to proceed, add a comment `// ASSUMPTION: <explanation>` and mention it in your final summary.
4. **ASK**: Prefer asking the user for clarification on business rules (e.g., "Should a 'Job' have a 'status'?").

4
docs/MOBILE/01-architecture-principles.md
View File

@@ -105,11 +105,11 @@ graph TD
- If not possible, and if that specific widget is used in multiple features, then try to create a shared widget in the `apps/mobile/packages/design_system/widgets`.
- Theme definitions (Colors, Typography).
- Assets (Icons, Images).
- More details on how to use this package is available in the `apps/mobile/docs/03-design-system-usage.md`.
- More details on how to use this package is available in the `apps/mobile/docs/02-design-system-usage.md`.
- **RESTRICTION**:
- CANNOT change colours or typography.
- Dumb widgets only. NO business logic. NO state management (Bloc).
- More details on how to use this package is available in the `apps/mobile/docs/03-design-system-usage.md`.
- More details on how to use this package is available in the `apps/mobile/docs/02-design-system-usage.md`.
### 2.6 Core Localization (`apps/mobile/packages/core_localization`)
- **Role**: Centralized language and localization management.

39
docs/MOBILE/04-use-case-completion-audit.md
View File

@@ -1,9 +1,10 @@
# 📊 Use Case Completion Audit
**Generated:** 2026-03-02
**Generated:** 2026-03-06
**Auditor Role:** System Analyst / Flutter Architect
**Source of Truth:** `docs/ARCHITECTURE/client-mobile-application/use-case.md`, `docs/ARCHITECTURE/staff-mobile-application/use-case.md`
**Codebase Checked:** `apps/mobile/packages/features/` and `apps/mobile/apps/` (actual production apps)
**Latest Milestone:** M4 (released 2026-03-05)
---
@@ -162,7 +163,7 @@
| 2.1 Browse & Filter Jobs | Filter by Distance | ✅ | ✅ Completed | Distance/radius filtering implemented in shifts module. |
| 2.1 Browse & Filter Jobs | View job card details | ✅ | ✅ Completed | Comprehensive job cards with pay, location, requirements. |
| 2.3 Set Availability | Select dates/times → Save preferences | ✅ | ✅ Completed | `availability_page.dart` + AvailabilityBloc with 3 use cases. |
| View Benefits | Browse available benefits | ✅ | 🚫 Completed | `benefits_overview_page.dart` (454 lines) fully implemented as part of home module. |
| View Benefits | Browse available benefits | ✅ | ✅ Completed | `benefits_overview_page.dart` in home module. Documented in M4 milestone. |
| Upcoming Shift Quick-Link | Next shift banner on home | ✅ | 🚫 Completed | Upcoming shifts display on worker home page. |
---
@@ -215,18 +216,18 @@
| Use Case | Sub-Use Case | Production App | Status | Notes |
|:---|:---|:---:|:---:|:---|
| 5.1 Manage Compliance Documents | Navigate to Compliance Menu | ✅ | ✅ Completed | Compliance section in `staff_profile_page.dart`. |
| 5.1 Manage Compliance Documents | Upload Certificates | ✅ | ✅ Completed | `certificates/` module with 4 use cases + 2 pages. |
| 5.1 Manage Compliance Documents | View/Manage Identity Documents | ✅ | ✅ Completed | `documents/` module with upload + view functionality. |
| 5.2 Manage Tax Forms | Complete W-4 digitally & submit | ✅ | ✅ Completed | `tax_forms/form_w4_page.dart` + FormW4Cubit + use cases. |
| 5.2 Manage Tax Forms | Complete I-9 digitally & submit | ✅ | ✅ Completed | `tax_forms/form_i9_page.dart` + FormI9Cubit + use cases. |
| 5.4 Account Settings | Update Bank Details | ✅ | ✅ Completed | `staff_bank_account/` module with page + cubit. |
| 5.4 Account Settings | Access Support / FAQs | ✅ | ✅ Completed | `faqs/` module with search functionality + 2 use cases. |
| Personal Info Management | Update profile information | ✅ | 🚫 Completed | `profile_info/` module with 3 pages (personal info, language, locations). |
| Emergency Contact | Manage emergency contacts | ✅ | 🚫 Completed | `emergency_contact/` module with get + save use cases. |
| Experience Management | Update industries and skills | ✅ | 🚫 Completed | `experience/` module with 3 use cases. |
| Attire Management | Upload attire photos | ✅ | 🚫 Completed | `attire/` module with upload + photo management. |
| Timecard Viewing | View clock-in/out history | ✅ | 🚫 Completed | `time_card/` module with get_time_cards use case. |
| Privacy & Security | Manage privacy settings | ✅ | 🚫 Completed | `privacy_security/` module with 4 use cases + 2 pages. |
| 5.1 Manage Compliance Documents | Upload Certificates | ✅ | ✅ Completed | `profile_sections/compliance/certificates/` module with 4 use cases + 2 pages. M4 feature. |
| 5.1 Manage Compliance Documents | View/Manage Identity Documents | ✅ | ✅ Completed | `profile_sections/compliance/documents/` module with camera/gallery upload. M4 feature. |
| 5.2 Manage Tax Forms | Complete W-4 digitally & submit | ✅ | ✅ Completed | `profile_sections/finances/tax_forms/form_w4_page.dart` + FormW4Cubit + use cases. |
| 5.2 Manage Tax Forms | Complete I-9 digitally & submit | ✅ | ✅ Completed | `profile_sections/finances/tax_forms/form_i9_page.dart` + FormI9Cubit + use cases. |
| 5.4 Account Settings | Update Bank Details | ✅ | ✅ Completed | `profile_sections/finances/staff_bank_account/` module with page + cubit. |
| 5.4 Account Settings | Access Support / FAQs | ✅ | ✅ Completed | `profile_sections/support/faqs/` module with search functionality + 2 use cases. |
| Personal Info Management | Update profile information | ✅ | ✅ Completed | `profile_sections/onboarding/profile_info/` module with 3 pages. Documented in M4. |
| Emergency Contact | Manage emergency contacts | ✅ | ✅ Completed | `profile_sections/onboarding/emergency_contact/` module. Documented in M4. |
| Experience Management | Update industries and skills | ✅ | ✅ Completed | `profile_sections/onboarding/experience/` module with 3 use cases. Documented in M4. |
| Attire Management | Upload attire photos & verification | ✅ | ✅ Completed | `profile_sections/compliance/attire/` module with camera/gallery support. Documented in M4. |
| Timecard Viewing | View clock-in/out history | ✅ | 🚫 Completed | `profile_sections/finances/time_card/` module with get_time_cards use case. |
| Privacy & Security | Manage privacy settings & visibility | ✅ | ✅ Completed | `profile_sections/support/privacy_security/` module with 4 use cases + 2 pages. Documented in M4. |
---
@@ -235,7 +236,6 @@
| Feature | Status | Notes |
|:---|:---:|:---|
| 5.3 KROW University Training | ❌ Missing | No training module exists. Module, video/quiz functionality not implemented. |
| 5.4 View Benefits | ✅ **Actually Implemented** | Found in home module as `benefits_overview_page.dart` (454 lines). |
| In-App Support Chat | ❌ Missing | No messaging module (only push notification support). |
| Leaderboard | ❌ Missing | No competitive tracking/gamification module. |
@@ -269,7 +269,7 @@
- ✅ Clock In/Out (GPS + NFC): 100%
- ✅ Payments & Early Pay: 100%
- ✅ Availability: 100%
- ✅ Profile & Compliance: 100% (11 subsections)
- ✅ Profile & Compliance: 100% (13 subsections via modular `profile_sections` structure)
- ❌ KROW University: 0% (training module not implemented)
---
@@ -292,7 +292,12 @@
- **Presentation** (pages, widgets, BLoCs)
- **Domain** (use cases, entities)
- **Data** (repositories, models, data sources)
- **Dependency injection** via GetIt
- **Dependency injection** via Flutter Modular
- **Modular Profile Sections** (M4): Staff profile features organized in `profile_sections/` with 4 sub-modules:
- `onboarding/` - Profile info, experience, emergency contacts
- `compliance/` - Documents, certificates, attire
- `finances/` - Bank account, tax forms, timecard
- `support/` - FAQs, privacy & security
### Known Technical Debt
- **Coverage Re-post**: Mutation exists but noted as stub in code (needs backend wiring)

64
docs/MOBILE/05-release-process.md Normal file
View File

@@ -0,0 +1,64 @@
# Mobile Release Process
**For complete release documentation, see: [docs/RELEASE/mobile-releases.md](../RELEASE/mobile-releases.md)**
---
## Quick Links
### Release Workflows
- **Product Release**: Trigger at: [GitHub Actions](https://github.com/Oloodi/krow-workforce/actions/workflows/product-release.yml)
- **Hotfix Creation**: Trigger at: [GitHub Actions](https://github.com/Oloodi/krow-workforce/actions/workflows/hotfix-branch-creation.yml)
### Key Concepts
**Versioning**: We use semantic versioning with milestone suffixes (e.g., `0.0.1-m4`)
- Defined in: `apps/mobile/apps/staff/pubspec.yaml` or `apps/mobile/apps/client/pubspec.yaml`
- Auto-extracted by workflows (no manual input required)
**CHANGELOGs**:
- Staff: `apps/mobile/apps/staff/CHANGELOG.md`
- Client: `apps/mobile/apps/client/CHANGELOG.md`
- Format: `## [v0.0.1-m4] - Milestone 4 - 2026-03-05`
**Git Tags**: `krow-withus-<app>-mobile/<env>-vX.Y.Z`
- Example: `krow-withus-worker-mobile/dev-v0.0.1-m4`
---
## Quick Start
### Standard Release
1. **Update CHANGELOG** with user-facing changes
2. **Update version** in `pubspec.yaml`
3. **Commit and push** to dev branch
4. **Trigger workflow**:
- Go to GitHub Actions → "📦 Product Release"
- Select app (worker/client) and environment (dev/stage/prod)
- Click "Run workflow"
### Hotfix Release
1. **Trigger workflow**:
- Go to GitHub Actions → "🚨 Product Hotfix - Create Branch"
- Enter current production version and issue description
- Workflow creates branch and updates version/CHANGELOG
2. **Fix bug** on hotfix branch
3. **Merge to main** and release to production
---
## For Complete Details
See the comprehensive documentation: **[docs/RELEASE/mobile-releases.md](../RELEASE/mobile-releases.md)**
This includes:
- ✅ Detailed versioning strategy
- ✅ CHANGELOG format guidelines
- ✅ Step-by-step release procedures
- ✅ APK signing setup (24 GitHub Secrets)
- ✅ Helper scripts reference
- ✅ Hotfix process
- ✅ Troubleshooting guide
- ✅ Release cadence (dev/stage/prod)

363
docs/RELEASE/APK_SIGNING_IMPLEMENTATION_SUMMARY.md
View File

@@ -1,363 +0,0 @@
# APK Signing Implementation - Complete Summary
**Status**: ✅ Implementation Complete | 🟡 Secrets Configuration Pending
**Last Updated**: 2024
---
## 📋 What Was Implemented
### 1. GitHub Actions Workflow Updates
**File**: `.github/workflows/product-release.yml`
**New Steps Added**:
1. **🔐 Setup APK Signing** (before build)
- Detects app (worker/client) and environment (dev/stage/prod)
- Decodes keystore from GitHub Secrets
- Sets CodeMagic-compatible environment variables
- Configures `CI=true` for build.gradle.kts detection
- Gracefully handles missing secrets with warnings
2. **✅ Verify APK Signature** (after build)
- Verifies APK is properly signed using `jarsigner`
- Displays certificate details
- Shows signer information
- Provides helpful warnings if unsigned
**How It Works**:
```yaml
Setup Signing:
- Reads: ${{ secrets.WORKER_KEYSTORE_DEV_BASE64 }}
- Decodes to: /tmp/keystores/release.jks
- Sets env: CI=true, CM_KEYSTORE_PATH_STAFF=/tmp/keystores/release.jks
Build APK:
- Runs: make mobile-staff-build PLATFORM=apk MODE=release
- build.gradle.kts detects CI=true
- Uses environment variables for signing
Verify Signature:
- Checks with: jarsigner -verify app-release.apk
- Displays certificate info
```
### 2. Documentation Created
**Files Created**:
| File | Purpose | Lines |
|------|---------|-------|
| [docs/RELEASE/APK_SIGNING_SETUP.md](../../docs/RELEASE/APK_SIGNING_SETUP.md) | Complete setup guide | 300+ |
| [docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md](../../docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md) | Quick reference checklist | 120+ |
| [.github/scripts/setup-github-secrets.sh](../../.github/scripts/setup-github-secrets.sh) | Helper script | 200+ |
### 3. Scripts Created
**File**: `.github/scripts/setup-github-secrets.sh`
**Purpose**: Interactive helper to:
- Show which secrets are needed
- Generate base64 from existing keystores
- Display keytool information
- Provide copy-paste commands
**Usage**:
```bash
./.github/scripts/setup-github-secrets.sh
```
---
## 🔑 GitHub Secrets Required
**Total: 24 Secrets** (6 keystores × 4 properties each)
### Secret Naming Pattern:
```
{APP}_KEYSTORE_{ENV}_BASE64
{APP}_KEYSTORE_PASSWORD_{ENV}
{APP}_KEY_ALIAS_{ENV}
{APP}_KEY_PASSWORD_{ENV}
```
Where:
- `{APP}` = `WORKER` or `CLIENT`
- `{ENV}` = `DEV`, `STAGING`, or `PROD`
### Full List:
**Worker Mobile (12 secrets)**:
- `WORKER_KEYSTORE_DEV_BASE64`, `WORKER_KEYSTORE_PASSWORD_DEV`, `WORKER_KEY_ALIAS_DEV`, `WORKER_KEY_PASSWORD_DEV`
- `WORKER_KEYSTORE_STAGING_BASE64`, `WORKER_KEYSTORE_PASSWORD_STAGING`, `WORKER_KEY_ALIAS_STAGING`, `WORKER_KEY_PASSWORD_STAGING`
- `WORKER_KEYSTORE_PROD_BASE64`, `WORKER_KEYSTORE_PASSWORD_PROD`, `WORKER_KEY_ALIAS_PROD`, `WORKER_KEY_PASSWORD_PROD`
**Client Mobile (12 secrets)**:
- `CLIENT_KEYSTORE_DEV_BASE64`, `CLIENT_KEYSTORE_PASSWORD_DEV`, `CLIENT_KEY_ALIAS_DEV`, `CLIENT_KEY_PASSWORD_DEV`
- `CLIENT_KEYSTORE_STAGING_BASE64`, `CLIENT_KEYSTORE_PASSWORD_STAGING`, `CLIENT_KEY_ALIAS_STAGING`, `CLIENT_KEY_PASSWORD_STAGING`
- `CLIENT_KEYSTORE_PROD_BASE64`, `CLIENT_KEYSTORE_PASSWORD_PROD`, `CLIENT_KEY_ALIAS_PROD`, `CLIENT_KEY_PASSWORD_PROD`
---
## 🚀 How to Configure
### Step 1: Prepare Dev Keystores
Dev keystores are already in the repository:
- Worker: `apps/mobile/apps/staff/android/app/krow_with_us_staff_dev.jks`
- Client: `apps/mobile/apps/client/android/app/krow_with_us_client_dev.jks`
Generate base64:
```bash
# Worker Dev
base64 -i apps/mobile/apps/staff/android/app/krow_with_us_staff_dev.jks
# Client Dev
base64 -i apps/mobile/apps/client/android/app/krow_with_us_client_dev.jks
```
### Step 2: Retrieve Staging/Prod Keystores
**Option A**: From CodeMagic
1. Go to CodeMagic → Team Settings → Code signing identities
2. Download keystores: `krow_staff_staging.jks`, `krow_staff_prod.jks`, etc.
3. Generate base64 for each
**Option B**: From Secure Storage
1. Retrieve from your organization's key management system
2. Generate base64 for each
### Step 3: Add to GitHub
1. Go to: **Repository → Settings → Secrets and variables → Actions**
2. Click: **New repository secret**
3. Add all 24 secrets (use checklist: [GITHUB_SECRETS_CHECKLIST.md](../../docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md))
### Step 4: Test the Workflow
```bash
# Test with dev environment first
# Go to: Actions → Product Release → Run workflow
# Select:
# - App: worker-mobile-app
# - Environment: dev
# - Version type: patch
# - Create GitHub Release: true
```
**Expected Output**:
```
🔐 Setting up Android signing for worker-mobile-app in dev environment...
✅ Keystore decoded successfully
📦 Keystore size: 3.2K
✅ Signing environment configured for STAFF (dev environment)
🔑 Using key alias: krow_staff_dev
📱 Building Staff (Worker) APK...
✅ APK built successfully
🔍 Verifying APK signature...
✅ APK is properly signed!
📜 Certificate Details: [shows cert info]
```
---
## 🔒 Security Considerations
### ✅ Safe Practices
1. **Dev keystores in repo**: Acceptable for development
- Committed: `krow_with_us_staff_dev.jks`, `krow_with_us_client_dev.jks`
- Password: `krowwithus` (public knowledge)
2. **Staging/Prod keystores**: ONLY in GitHub Secrets
- Never commit to repository
- Encrypted at rest by GitHub
- Only accessible in workflow runs
3. **Keystore cleanup**: Workflow stores in `${{ runner.temp }}`
- Automatically deleted after job completes
- Not persisted in artifacts or logs
### ⚠️ Important Notes
1. **Same keystores as CodeMagic**: Use identical keystores to ensure app updates work
2. **Signature consistency**: Apps signed with different keystores cannot update each other
3. **Key rotation**: Document process for rotating production keys
4. **Backup keystores**: Keep secure backups - lost keystores = can't update app
---
## 🧪 Testing Checklist
Before using in production:
- [ ] Configure all 24 GitHub Secrets
- [ ] Run workflow with `dev` environment
- [ ] Download APK artifact
- [ ] Verify signature: `jarsigner -verify -verbose app.apk`
- [ ] Install APK on Android device
- [ ] Launch app and verify functionality
- [ ] Compare signature fingerprints with CodeMagic builds
- [ ] Test `stage` environment
- [ ] Test `prod` environment (after full validation)
---
## 📊 Architecture Overview
```
┌─────────────────────────────────────────────────────────────┐
│ GitHub Actions Workflow: product-release.yml │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. Validate & Create Release │
│ └─> Extract version from pubspec.yaml │
│ └─> Create Git tag │
│ └─> Create GitHub Release │
│ │
│ 2. Build Mobile Artifacts │
│ │ │
│ ├─> Setup Node.js + Firebase CLI │
│ ├─> Setup Java 17 │
│ ├─> Setup Flutter 3.24.5 │
│ ├─> Install Melos │
│ ├─> Install Dependencies │
│ │ │
│ ├─> 🔐 Setup APK Signing (NEW) │
│ │ ├─> Detect app (worker/client) │
│ │ ├─> Detect environment (dev/stage/prod) │
│ │ ├─> Read GitHub Secret: │
│ │ │ {APP}_KEYSTORE_{ENV}_BASE64 │
│ │ ├─> Decode base64 → .jks file │
│ │ ├─> Set environment variables: │
│ │ │ - CI=true │
│ │ │ - CM_KEYSTORE_PATH_STAFF=/tmp/keystore.jks │
│ │ │ - CM_KEYSTORE_PASSWORD_STAFF=*** │
│ │ │ - CM_KEY_ALIAS_STAFF=krow_staff_dev │
│ │ │ - CM_KEY_PASSWORD_STAFF=*** │
│ │ └─> ✅ Ready for signed build │
│ │ │
│ ├─> 🏗️ Build APK │
│ │ └─> make mobile-staff-build PLATFORM=apk │
│ │ └─> Flutter build detects CI=true │
│ │ └─> build.gradle.kts uses env vars │
│ │ └─> Signs APK with keystore │
│ │ │
│ ├─> ✅ Verify APK Signature (NEW) │
│ │ ├─> jarsigner -verify app-release.apk │
│ │ ├─> Show certificate details │
│ │ └─> Confirm signing successful │
│ │ │
│ ├─> 📤 Upload APK as Artifact │
│ │ └─> 30-day retention in GitHub Actions │
│ │ │
│ └─> 📦 Attach APK to GitHub Release │
│ └─> krow-withus-worker-mobile-dev-v0.1.0.apk │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Build Configuration: build.gradle.kts │
├─────────────────────────────────────────────────────────────┤
│ │
│ signingConfigs { │
│ create("release") { │
│ if (System.getenv()["CI"] == "true") { │
│ // ✅ GitHub Actions / CodeMagic │
│ storeFile = file( │
│ System.getenv()["CM_KEYSTORE_PATH_STAFF"] │
│ ) │
│ storePassword = │
│ System.getenv()["CM_KEYSTORE_PASSWORD_*"] │
│ keyAlias = │
│ System.getenv()["CM_KEY_ALIAS_*"] │
│ keyPassword = │
│ System.getenv()["CM_KEY_PASSWORD_*"] │
│ } else { │
│ // Local Development │
│ use key.properties file │
│ } │
│ } │
│ } │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## 📖 Documentation Index
1. **[APK_SIGNING_SETUP.md](../../docs/RELEASE/APK_SIGNING_SETUP.md)**
- Complete setup guide with all details
- Security best practices
- Troubleshooting guide
- Keystore management commands
2. **[GITHUB_SECRETS_CHECKLIST.md](../../docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md)**
- Quick reference for all 24 secrets
- Copy-paste checklist
- Dev environment values
3. **[setup-mobile-github-secrets.sh](../../.github/scripts/setup-mobile-github-secrets.sh)**
- Interactive helper script
- Shows existing keystores
- Generates base64 commands
- Displays keytool info
4. **[product-release.yml](../../.github/workflows/product-release.yml)**
- Updated workflow with signing
- Lines 198-294: Setup APK Signing
- Lines 330-364: Verify APK Signature
---
## ✅ Next Steps
### Immediate (Required for Signed APKs)
1. **Configure GitHub Secrets** (30 minutes)
- Start with dev environment (test first)
- Use helper script: `.github/scripts/setup-mobile-github-secrets.sh`
- Follow checklist: `docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md`
2. **Test Dev Signing** (15 minutes)
- Run workflow with dev environment
- Download APK and verify signature
- Install on device and test
3. **Configure Staging/Prod** (30 minutes)
- Retrieve keystores from CodeMagic/secure storage
- Add to GitHub Secrets
- Test each environment
### Future Enhancements (Optional)
- [ ] Add AAB (Android App Bundle) support for Play Store
- [ ] Implement iOS signing for IPA files
- [ ] Add automated Play Store upload
- [ ] Set up GitHub Environments with protection rules
- [ ] Add Slack notifications for releases
---
## 🆘 Support
If you encounter issues:
1. Check workflow logs for signing step output
2. Verify GitHub Secrets are configured correctly
3. Run helper script: `.github/scripts/setup-mobile-github-secrets.sh`
4. Review: `docs/RELEASE/APK_SIGNING_SETUP.md` → Troubleshooting section
**Common Issues**:
- "Keystore not found" → Secret not configured or wrong name
- "Wrong password" → Secret value doesn't match actual keystore
- APK unsigned → CI=true not set or build.gradle.kts issue
- App won't install over existing → Different keystore used
---
**Implementation Date**: 2024
**Implemented By**: GitHub Copilot (Claude Sonnet 4.5)
**Status**: ✅ Code Complete | 🟡 Awaiting Secrets Configuration

282
docs/RELEASE/APK_SIGNING_SETUP.md
View File

@@ -1,282 +0,0 @@
# APK Signing Setup for GitHub Actions
**For Worker Mobile & Client Mobile Apps**
---
## 📋 Overview
This document explains how to set up APK signing for automated builds in GitHub Actions. The same keystore files used in CodeMagic will be used here.
---
## 🔑 Understanding App Signing
### Why Sign APKs?
- **Required by Google Play**: All Android apps must be signed before distribution
- **App Identity**: The signature identifies your app across updates
- **Security**: Ensures the APK hasn't been tampered with
### Keystore Files
Each app and environment combination has its own keystore:
**Worker Mobile (Staff App):**
- `krow_staff_dev.jks` - Development builds
- `krow_staff_staging.jks` - Staging builds
- `krow_staff_prod.jks` - Production builds
**Client Mobile:**
- `krow_client_dev.jks` - Development builds
- `krow_client_staging.jks` - Staging builds
- `krow_client_prod.jks` - Production builds
### Current State
- ✅ **Dev keystores** are committed to the repository (in `apps/mobile/apps/*/android/app/`)
- ⚠️ **Staging/Prod keystores** are stored securely in CodeMagic (NOT in repo)
---
## 🔐 GitHub Secrets Setup
### Step 1: Export Keystores as Base64
For staging and production keystores (stored in CodeMagic), you'll need to:
```bash
# On your local machine with access to the keystore files:
# For Worker Mobile - Staging
base64 -i krow_staff_staging.jks -o krow_staff_staging.jks.base64
# For Worker Mobile - Production
base64 -i krow_staff_prod.jks -o krow_staff_prod.jks.base64
# For Client Mobile - Staging
base64 -i krow_client_staging.jks -o krow_client_staging.jks.base64
# For Client Mobile - Production
base64 -i krow_client_prod.jks -o krow_client_prod.jks.base64
```
### Step 2: Create GitHub Secrets
Go to: **GitHub Repository → Settings → Secrets and variables → Actions → New repository secret**
Create the following secrets:
#### Worker Mobile (Staff App) Secrets
| Secret Name | Value | Environment |
|-------------|-------|-------------|
| `WORKER_KEYSTORE_DEV_BASE64` | (base64 of dev keystore) | dev |
| `WORKER_KEYSTORE_STAGING_BASE64` | (base64 of staging keystore) | stage |
| `WORKER_KEYSTORE_PROD_BASE64` | (base64 of prod keystore) | prod |
| `WORKER_KEYSTORE_PASSWORD_DEV` | `krowwithus` | dev |
| `WORKER_KEYSTORE_PASSWORD_STAGING` | (actual staging password) | stage |
| `WORKER_KEYSTORE_PASSWORD_PROD` | (actual prod password) | prod |
| `WORKER_KEY_ALIAS_DEV` | `krow_staff_dev` | dev |
| `WORKER_KEY_ALIAS_STAGING` | (actual staging alias) | stage |
| `WORKER_KEY_ALIAS_PROD` | (actual prod alias) | prod |
| `WORKER_KEY_PASSWORD_DEV` | `krowwithus` | dev |
| `WORKER_KEY_PASSWORD_STAGING` | (actual staging key password) | stage |
| `WORKER_KEY_PASSWORD_PROD` | (actual prod key password) | prod |
#### Client Mobile Secrets
| Secret Name | Value | Environment |
|-------------|-------|-------------|
| `CLIENT_KEYSTORE_DEV_BASE64` | (base64 of dev keystore) | dev |
| `CLIENT_KEYSTORE_STAGING_BASE64` | (base64 of staging keystore) | stage |
| `CLIENT_KEYSTORE_PROD_BASE64` | (base64 of prod keystore) | prod |
| `CLIENT_KEYSTORE_PASSWORD_DEV` | `krowwithus` | dev |
| `CLIENT_KEYSTORE_PASSWORD_STAGING` | (actual staging password) | stage |
| `CLIENT_KEYSTORE_PASSWORD_PROD` | (actual prod password) | prod |
| `CLIENT_KEY_ALIAS_DEV` | `krow_client_dev` | dev |
| `CLIENT_KEY_ALIAS_STAGING` | (actual staging alias) | stage |
| `CLIENT_KEY_ALIAS_PROD` | (actual prod alias) | prod |
| `CLIENT_KEY_PASSWORD_DEV` | `krowwithus` | dev |
| `CLIENT_KEY_PASSWORD_STAGING` | (actual staging key password) | stage |
| `CLIENT_KEY_PASSWORD_PROD` | (actual prod key password) | prod |
---
## ⚙️ How It Works in GitHub Actions
### Build Configuration Detection
The `build.gradle.kts` files check for `CI=true` environment variable:
```kotlin
signingConfigs {
create("release") {
if (System.getenv()["CI"] == "true") {
// CI environment (CodeMagic or GitHub Actions)
storeFile = file(System.getenv()["CM_KEYSTORE_PATH_STAFF"] ?: "")
storePassword = System.getenv()["CM_KEYSTORE_PASSWORD_STAFF"]
keyAlias = System.getenv()["CM_KEY_ALIAS_STAFF"]
keyPassword = System.getenv()["CM_KEY_PASSWORD_STAFF"]
} else {
// Local development (uses key.properties)
keyAlias = keystoreProperties["keyAlias"] as String?
keyPassword = keystoreProperties["keyPassword"] as String?
storeFile = keystoreProperties["storeFile"]?.let { file(it) }
storePassword = keystoreProperties["storePassword"] as String?
}
}
}
```
### GitHub Actions Workflow Steps
1. **Decode Keystore**: Convert base64 secret back to `.jks` file
2. **Set Environment Variables**: Provide the same env vars CodeMagic uses
3. **Build APK**: Flutter build automatically uses the signing config
4. **Verify Signature**: Optionally verify the APK is signed correctly
---
## 🚀 Usage
### For Development Builds
Dev keystores are already in the repo, so GitHub Actions will automatically use them:
```bash
# No special setup needed for dev builds
# They use committed keystores: krow_with_us_staff_dev.jks
```
### For Staging/Production Builds
Once GitHub Secrets are configured (Step 2 above), the workflow will:
1. Detect the environment (dev/stage/prod)
2. Use the appropriate keystore secret
3. Decode it before building
4. Sign the APK automatically
---
## ✅ Verification
### Check APK Signature
After building, verify the APK is signed:
```bash
# Using keytool (part of Java JDK)
keytool -printcert -jarfile app-release.apk
# Expected output should show certificate info with your key alias
```
### Check Build Logs
In GitHub Actions, look for:
```
✅ Keystore decoded successfully
✅ APK signed with: krow_staff_prod
✅ APK built successfully: /path/to/app-release.apk
```
---
## 🔒 Security Best Practices
### DO:
- ✅ Store production keystores ONLY in GitHub Secrets (encrypted)
- ✅ Use different keystores for dev/staging/prod
- ✅ Rotate passwords periodically
- ✅ Limit access to repository secrets (use environment protection rules)
- ✅ Keep keystore files backed up securely offline
### DON'T:
- ❌ Never commit staging/production keystores to Git
- ❌ Never share keystore passwords in plain text
- ❌ Never use production keystores for development
- ❌ Never commit `.jks` files for staging/prod
---
## 📝 Keystore Management Commands
### Generate New Keystore
```bash
keytool -genkey -v \
-keystore krow_staff_prod.jks \
-alias krow_staff_prod \
-keyalg RSA \
-keysize 2048 \
-validity 10000 \
-storetype JKS
```
### View Keystore Info
```bash
keytool -list -v -keystore krow_staff_prod.jks
```
### Get SHA-1 and SHA-256 Fingerprints
```bash
keytool -list -v -keystore krow_staff_prod.jks -alias krow_staff_prod
```
These fingerprints are needed for:
- Firebase project configuration
- Google Maps API key restrictions
- Google Play Console app signing
---
## 🆘 Troubleshooting
### "keystore not found" Error
**Problem**: GitHub Actions can't find the decoded keystore
**Solution**: Check the decode step in the workflow creates the file in the correct location
### "wrong password" Error
**Problem**: Keystore password doesn't match
**Solution**: Verify the GitHub Secret value matches the actual keystore password
### APK Not Signed
**Problem**: APK builds but isn't signed
**Solution**: Ensure `CI=true` is set before building
### Certificate Mismatch
**Problem**: "App not installed" when updating
**Solution**: You're using a different keystore than previous builds. Use the same keystore for all versions.
---
## 📚 Related Documentation
- [Product Release Workflow](./MOBILE_RELEASE_PLAN.md)
- [Hotfix Process](./HOTFIX_PROCESS.md)
- [CodeMagic Configuration](/codemagic.yaml)
- [Android App Signing (Google Docs)](https://developer.android.com/studio/publish/app-signing)
---
## 🔄 Migration from CodeMagic
If you want to use GitHub Actions instead of CodeMagic:
1. Export all keystores from CodeMagic
2. Convert to base64 (as shown above)
3. Add to GitHub Secrets
4. Test with a dev build first
5. Verify signatures match previous releases
6. Deploy staging build for testing
7. Only then use for production
**Important**: Make sure the GitHub Actions builds produce the SAME signature as CodeMagic builds, otherwise app updates will fail!

115
docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md
View File

@@ -1,115 +0,0 @@
# GitHub Secrets Checklist for APK Signing
**Quick reference for repository secret configuration**
📍 **Configure at**: Repository Settings → Secrets and variables → Actions
---
## ✅ Worker Mobile (Staff App) - 12 Secrets
### Dev Environment
- [ ] `WORKER_KEYSTORE_DEV_BASE64`
- [ ] `WORKER_KEYSTORE_PASSWORD_DEV`
- [ ] `WORKER_KEY_ALIAS_DEV`
- [ ] `WORKER_KEY_PASSWORD_DEV`
### Staging Environment
- [ ] `WORKER_KEYSTORE_STAGING_BASE64`
- [ ] `WORKER_KEYSTORE_PASSWORD_STAGING`
- [ ] `WORKER_KEY_ALIAS_STAGING`
- [ ] `WORKER_KEY_PASSWORD_STAGING`
### Production Environment
- [ ] `WORKER_KEYSTORE_PROD_BASE64`
- [ ] `WORKER_KEYSTORE_PASSWORD_PROD`
- [ ] `WORKER_KEY_ALIAS_PROD`
- [ ] `WORKER_KEY_PASSWORD_PROD`
---
## ✅ Client Mobile - 12 Secrets
### Dev Environment
- [ ] `CLIENT_KEYSTORE_DEV_BASE64`
- [ ] `CLIENT_KEYSTORE_PASSWORD_DEV`
- [ ] `CLIENT_KEY_ALIAS_DEV`
- [ ] `CLIENT_KEY_PASSWORD_DEV`
### Staging Environment
- [ ] `CLIENT_KEYSTORE_STAGING_BASE64`
- [ ] `CLIENT_KEYSTORE_PASSWORD_STAGING`
- [ ] `CLIENT_KEY_ALIAS_STAGING`
- [ ] `CLIENT_KEY_PASSWORD_STAGING`
### Production Environment
- [ ] `CLIENT_KEYSTORE_PROD_BASE64`
- [ ] `CLIENT_KEYSTORE_PASSWORD_PROD`
- [ ] `CLIENT_KEY_ALIAS_PROD`
- [ ] `CLIENT_KEY_PASSWORD_PROD`
---
## 📦 Total: 24 Secrets
**Status**: ⬜ Not Started | 🟡 In Progress | ✅ Complete
---
## 🔧 Quick Setup Commands
### Generate base64 for existing keystores:
```bash
# Worker Mobile Dev (already in repo)
base64 -i apps/mobile/apps/staff/android/app/krow_with_us_staff_dev.jks
# Client Mobile Dev (already in repo)
base64 -i apps/mobile/apps/client/android/app/krow_with_us_client_dev.jks
# For staging/prod keystores (retrieve from secure storage first):
base64 -i /path/to/krow_staff_staging.jks
base64 -i /path/to/krow_staff_prod.jks
base64 -i /path/to/krow_client_staging.jks
base64 -i /path/to/krow_client_prod.jks
```
### Or use the helper script:
```bash
.github/scripts/setup-mobile-github-secrets.sh
```
---
## 📋 Dev Environment Values (Public - Already in Repo)
**Worker Mobile:**
- Password: `krowwithus`
- Alias: `krow_staff_dev`
- Key Password: `krowwithus`
- Keystore: `apps/mobile/apps/staff/android/app/krow_with_us_staff_dev.jks`
**Client Mobile:**
- Password: `krowwithus`
- Alias: `krow_client_dev`
- Key Password: `krowwithus`
- Keystore: `apps/mobile/apps/client/android/app/krow_with_us_client_dev.jks`
---
## 🚨 Important Notes
1. **Staging/Production keystores** should NEVER be committed to the repository
2. Retrieve staging/prod keystores from:
- CodeMagic Team Settings → Code signing identities
- Or your organization's secure key management system
3. Keep keystore passwords in a password manager
4. Test with **dev environment first** before configuring staging/prod
---
## 📚 Related Documentation
- [Complete Setup Guide](./APK_SIGNING_SETUP.md)
- [Release Workflow](./MOBILE_RELEASE_PLAN.md)

343
docs/RELEASE/HOTFIX_PROCESS.md
View File

@@ -1,343 +0,0 @@
# Hotfix Process
**For Emergency Production Fixes**
---
## 🚨 When to Hotfix
Use hotfix when:
- ✅ Critical bug in production affecting users
- ✅ Data loss or security vulnerability
- ✅ Service unavailable or major feature broken
- ✅ Customer-blocking issue
**Don't use hotfix for:**
- ❌ Minor bugs (can wait for next release)
- ❌ Feature requests
- ❌ Nice-to-have improvements
- ❌ Styling issues
---
## 🔄 Hotfix Process
### Step 1: Assess & Declare Emergency
```
Issue: [Brief description]
Severity: CRITICAL / HIGH / MEDIUM
Product: [Staff Mobile / Client Mobile / Web / Backend]
Environment: Production
Impact: [How many users affected]
```
Once severity confirmed → Start hotfix immediately.
---
### Step 2: Create Hotfix Branch
```bash
# From production tag
git checkout -b hotfix/krow-withus-worker-mobile-v0.1.1 \
krow-withus-worker-mobile/prod-v0.1.0
# Verify you're on the right tag
git log -1 --oneline
```
**Format**: `hotfix/<product>-v<PATCH+1>`
---
### Step 3: Fix the Bug
```bash
# Make your fix
# Edit files, test locally
# Commit with clear message
git commit -m "fix: [issue description]
HOTFIX for production
Issue: [what happened]
Solution: [what was fixed]
Tested: [how was it tested locally]"
```
**Keep it minimal:**
- Only fix the specific bug
- Don't refactor or optimize
- Don't add new features
---
### Step 4: Update Version
Update PATCH version only (0.1.0 → 0.1.1):
**For Mobile** (`apps/mobile/apps/*/pubspec.yaml`):
```yaml
# Old
version: 0.1.0+5
# New
version: 0.1.1+6 # Only PATCH changed
```
**For Web** (`apps/web/package.json`):
```json
"version": "0.1.1"
```
**For Backend** (`backend/*/package.json`):
```json
"version": "0.1.1"
```
---
### Step 5: Update CHANGELOG
Add entry to **top** of appropriate CHANGELOG:
```markdown
| 2026-03-05 | 0.1.1 | HOTFIX: [Issue fixed] |
(previous entries below...)
```
---
### Step 6: Code Review (Expedited)
```bash
# Push hotfix branch
git push origin hotfix/krow-withus-worker-mobile-v0.1.1
# Create PR on GitHub with URGENT label
gh pr create --title "HOTFIX: [Issue description]" \
--body "**URGENT PRODUCTION FIX**
Issue: [What was broken]
Impact: [Users affected]
Solution: [What was fixed]
Testing: [Local verification]"
```
**Get approval within 15 minutes if possible.**
---
### Step 7: Merge to Main
```bash
# Review complete - merge
git checkout main
git pull origin main
git merge --ff-only hotfix/krow-withus-worker-mobile-v0.1.1
git push origin main
```
---
### Step 8: Create Production Tag
```bash
# Create tag from main
git tag -a krow-withus-worker-mobile/prod-v0.1.1 \
-m "HOTFIX: [Issue fixed]"
git push origin krow-withus-worker-mobile/prod-v0.1.1
```
---
### Step 9: Deploy to Production
```bash
# Follow your deployment procedure
# Higher priority than normal releases
./scripts/deploy-mobile-production.sh krow-withus-worker-mobile/prod-v0.1.1
```
**Deployment time**: Within 30 minutes of approval
---
### Step 10: Verify & Monitor
```bash
# Smoke tests
- App launches
- Core features work
- No new errors
# Monitor for 2 hours
- Watch error logs
- Check user reports
- Verify fix worked
```
---
### Step 11: Communicate
**Immediately after deployment:**
```markdown
🚨 PRODUCTION HOTFIX DEPLOYED
Product: Worker Mobile
Version: 0.1.1
Issue: [Fixed issue]
Impact: [Resolved for X users]
Status: ✅ Deployed & verified
No user action required.
Service restored to normal.
```
**24 hours later:**
```markdown
✅ HOTFIX STATUS UPDATE
Production hotfix v0.1.1 deployed 24 hours ago.
Zero errors reported post-deployment.
System stable.
Thank you for your patience!
```
---
## ⏱️ Timeline
```
T-0: Issue detected & reported
T+5min: Severity assessed, hotfix branch created
T+15: Fix implemented, code review started
T+30: Approved & merged, tag created
T+45: Deployed to production
T+60: Smoke tests pass, monitoring enabled
T+120: Declare emergency resolved, communicate
T+1day: Follow-up communication
```
**Total time: 2-4 hours from detection to resolution**
---
## 🚫 Common Mistakes to Avoid
❌ **Don't**:
- Skip code review (even in emergency)
- Add multiple unrelated fixes in one hotfix
- Forget to update version number
- Forget CHANGELOG entry
- Deploy without testing
- Forget to communicate with users
✅ **Do**:
- Keep hotfix minimal and focused
- Test every fix locally first
- Get at least one approval
- Update all version files
- Deploy immediately after approval
- Monitor actively for 2+ hours
---
## 📋 Hotfix Checklist
Copy for each emergency:
```
Hotfix: [Product] v[Old Version] → v[New Version]
□ Severity assessed & documented
□ Branch created from production tag
□ Bug fixed & tested locally
□ Version number updated (PATCH only)
□ CHANGELOG entry added
□ Commit message clear
□ Code review requested (marked URGENT)
□ Approval obtained
□ Merged to main
□ Production tag created
□ Tag pushed to remote
□ Deployed to production
□ Smoke tests passed
□ Error logs monitored (2+ hours)
□ Users notified
□ GitHub Release created
□ Incident documented
Total Time: ___ minutes
```
---
## 🔍 Post-Incident
After emergency is resolved:
1. **Document what happened**
- Root cause analysis
- Why it wasn't caught before
- What testing was missed
2. **Schedule postmortem** (within 24 hours)
- Review what went wrong
- Discuss prevention
- Update processes if needed
3. **Plan prevention**
- Add test coverage
- Update CI/CD checks
- Improve monitoring
4. **Communicate findings**
- Share with team
- Update documentation
- Prevent recurrence
---
## 📞 Emergency Contacts
When issue detected:
1. **Notify**:
- Release Engineer
- DevOps
- Product Owner
- Affected Team
2. **Communication Channel**:
- Slack: #emergency-releases
- Time-sensitive decisions on call
3. **Decision Maker**:
- Product Owner approves rollback vs hotfix
- Release Engineer executes
- DevOps monitors infrastructure
---
## 🔗 Related
- [OVERALL_RELEASE_PLAN.md](./OVERALL_RELEASE_PLAN.md) - Main release strategy
- [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) - Mobile-specific process
- [../../CHANGELOG.md](../../CHANGELOG.md) - Version history
---
**Last Updated**: 2026-03-05
**Severity Levels**:
- 🔴 CRITICAL: Service down, data loss, security (< 1 hour)
- 🟠 HIGH: Major feature broken, workaround available (< 4 hours)
- 🟡 MEDIUM: Minor feature affected (next release OK)

564
docs/RELEASE/MOBILE_RELEASE_PLAN.md
View File

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

452
docs/RELEASE/OVERALL_RELEASE_PLAN.md
View File

@@ -1,452 +0,0 @@
# KROW Workforce - Overall Release Plan
**Document Version**: 1.0
**Created**: 2026-03-05
**Last Updated**: 2026-03-05
**Product Scope**: All products (Mobile, Web, Backend, Database)
---
## 📋 Overview
This document outlines the release strategy for KROW Workforce monorepo containing 5 products:
1. **Staff Mobile App** (Flutter - iOS/Android)
2. **Client Mobile App** (Flutter - iOS/Android)
3. **Web Dashboard** (React/Vite)
4. **Backend Services** (Node.js - Command API, Core API)
5. **Database** (Firebase Data Connect with PostgreSQL)
---
## 🔗 Versioning Strategy
### Semantic Versioning (SemVer)
All products use **Semantic Versioning 2.0.0**:
```
MAJOR.MINOR.PATCH-QUALIFIER
0.1.0
1.2.3-rc.1
```
- **MAJOR** (0→1): Breaking changes, major features
- **MINOR** (1→2): Backward-compatible new features
- **PATCH** (3→4): Bug fixes, minor improvements
- **QUALIFIER** (optional): `-rc.1`, `-beta.1`, `-hotfix.1`
### Version Independence
Each product maintains **independent versioning**:
- Products release on their own schedule
- No requirement to synchronize versions
- Can release major updates independently
---
## 🏷️ Git Tag Naming Convention
### Standard Format
```
<product>/<environment>-v<major>.<minor>.<patch>
```
### Products & Environments
| Product | Tag Prefix | Environments |
|---------|-----------|---------------|
| Staff Mobile | `krow-withus-worker-mobile` | dev, stage, prod |
| Client Mobile | `krow-withus-client-mobile` | dev, stage, prod |
| Web Dashboard | `web-dashboard` | dev, stage, prod |
| Command API | `command-api` | dev, stage, prod |
| Core API | `core-api` | dev, stage, prod |
| DataConnect | `dataconnect` | stage, prod |
### Environments
- **dev**: Development releases (daily/weekly), unstable
- **stage**: Staging releases (bi-weekly), pre-production testing
- **prod**: Production releases (monthly), stable, customer-facing
### Examples
```
krow-withus-worker-mobile/dev-v0.1.0
krow-withus-client-mobile/stage-v0.2.0
web-dashboard/prod-v1.0.0
command-api/dev-v0.2.1
core-api/prod-v0.1.0
```
---
## 📅 Release Cadence
### Development Releases (dev)
- **Frequency**: Weekly or as-needed
- **Scope**: Feature completions, bug fixes
- **Duration**: Not guaranteed stable
- **Deployment**: Dev environment only
- **Who**: Development team
### Staging Releases (stage)
- **Frequency**: Bi-weekly (typically mid/end of sprint)
- **Scope**: Sprint completion, feature milestones
- **Duration**: 1-2 weeks stability expected
- **Deployment**: Staging environment for QA
- **Who**: QA team validates
### Production Releases (prod)
- **Frequency**: Monthly or sprint-based
- **Scope**: Feature milestone completion, critical fixes
- **Duration**: 4+ weeks standard support
- **Deployment**: Production environment (customer-facing)
- **Who**: Product owner approves, DevOps deploys
---
## 🔄 Product Dependency & Deployment Order
### Critical Path (for synchronized releases)
Deploy in this order:
1. **DataConnect Schema** (if schema changed)
- Deploy schema changes first
- All APIs depend on schema availability
2. **Backend Services** (parallel OK)
- Command API
- Core API
- Both can deploy simultaneously
3. **Web Dashboard**
- Can deploy once backend ready
- Test API endpoints stable
4. **Mobile Apps** (parallel OK)
- Staff Mobile
- Client Mobile
- Both can deploy simultaneously, independent of web
### Independent Releases
Products **can release independently** if:
- No backend schema changes
- No breaking API changes
- No data migrations required
Example: Staff Mobile can release UI improvements without web/backend changes.
---
## 📝 CHANGELOG Management
### Location & Structure
Each major product maintains its own CHANGELOG:
```
apps/mobile/packages/features/staff/*/CHANGELOG.md
apps/mobile/packages/features/client/*/CHANGELOG.md
apps/web/CHANGELOG.md
backend/command-api/CHANGELOG.md
backend/core-api/CHANGELOG.md
CHANGELOG.md (root - high-level overview)
```
### Format
```markdown
| Date | Version | Change |
|------|---------|--------|
| 2026-03-05 | 0.1.0 | Initial release - [feature list] |
```
### What to Track
- Features added
- Bugs fixed
- Breaking changes (clearly marked ⚠️)
- Dependencies upgraded
- Migration steps (if applicable)
---
## ✅ Release Checklist
### Pre-Release (48 hours before)
- [ ] All PRs merged to main
- [ ] Code review complete
- [ ] All tests passing (unit, integration, E2E)
- [ ] No lint/type errors
- [ ] Mobile builds succeed (CodeMagic)
- [ ] Performance benchmarks acceptable
- [ ] Security scan completed
- [ ] CHANGELOG.md updated with all changes
- [ ] Documentation updated
- [ ] Team notified of pending release
### Release Day
- [ ] Update version numbers in all relevant files
- [ ] Update CHANGELOG with date
- [ ] Git commit: `git commit -m "chore: bump version to X.Y.Z"`
- [ ] Git push changes to main
- [ ] Create git tag: `git tag -a <product>/<env>-v<version> -m "Release message"`
- [ ] Push tags: `git push origin <tag-name>`
- [ ] Deploy to target environment
- [ ] Smoke tests pass
- [ ] Create GitHub Release page
- [ ] Notify stakeholders
### Post-Release (24 hours)
- [ ] Monitor error logs
- [ ] Verify all features work end-to-end
- [ ] Performance is acceptable
- [ ] No regressions reported
- [ ] Users updated if needed
- [ ] Document any issues
---
## 🔐 Protected Tags
### Branch Protection Rules
**Production tags require approval:**
- Tag pattern: `*/prod-v*`
- Require pull request review (1+ approval)
- Require status checks to pass
- Prevent force pushes
- Disable deletions
**Staging tags recommended:**
- Tag pattern: `*/stage-v*`
- Consider: Require at least 1 approval
- Status checks should pass
**Dev tags open:**
- Tag pattern: `*/dev-v*`
- No restrictions
- Allow fast iteration
---
## 🚨 Rollback Procedures
### For Production Issues
**If critical issue detected:**
1. **Identify** the product and issue
2. **Assess** impact and severity
3. **Decide** rollback vs hotfix
- Rollback: Undo entire release
- Hotfix: Fix and re-release (see HOTFIX_PROCESS.md)
4. **Execute** rollback:
```bash
# Revert commit
git revert <commit-hash> -m 1
git push origin main
# Or switch traffic back to previous version
# (depends on deployment infrastructure)
```
5. **Communicate** with users
6. **Plan** hotfix or next release
### Time Windows
- **Awareness**: 15-30 minutes (monitoring)
- **Decision**: 15-30 minutes (severity assessment)
- **Execution**: 15-60 minutes (rollback deployment)
- **Verification**: 30-60 minutes (smoke tests)
- **Communication**: Immediate + 24h updates
**Total**: 2-4 hours from detection to stable state
---
## 📊 Release Templates & Tools
### Git Commands
```bash
# Create tag
git tag -a krow-withus-worker-mobile/dev-v0.1.0 \
-m "Staff Mobile v0.1.0 - Feature X"
# Push tag
git push origin krow-withus-worker-mobile/dev-v0.1.0
# View tags for product
git tag -l "krow-withus-worker-mobile/*" --sort=-version:refname
# See what's in a tag
git show krow-withus-worker-mobile/dev-v0.1.0
# Delete tag (if mistake)
git tag -d krow-withus-worker-mobile/dev-v0.1.0
git push origin --delete krow-withus-worker-mobile/dev-v0.1.0
```
### GitHub Release Template
```markdown
# Krow With Us - Worker Mobile - DEV - v0.1.0
**Release Date**: [Date]
**Environment**: Development
## What's New
### ✨ Features
- Feature 1 description
- Feature 2 description
### 🔧 Improvements
- Improvement 1
- Improvement 2
### 🐛 Bug Fixes
- Bug fix 1
- Bug fix 2
## Dependencies
Requires:
- Backend API v0.1.0 or higher
- DataConnect schema v0.3.0 (if updated)
## Installation
[Download links & instructions]
## Known Issues
- Issue 1: [desc] (Workaround: ...)
## Support
contact: support@krow-workforce.com
```
---
## 🔄 Hotfix Releases
See [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) for emergency procedures.
Quick summary:
1. Branch from production tag
2. Fix the issue
3. Bump PATCH version only
4. Test and deploy immediately
5. Create hotfix tag
---
## 📱 Mobile-Specific Release Process
See [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) for detailed mobile app process including:
- Staff Mobile vs Client Mobile differences
- Build number management
- CodeMagic integration
- App store distribution
- CHANGELOG per app
---
## 🎯 Release Coordination
### Single Product Release
1. Update version files
2. Update CHANGELOG
3. Commit & push
4. Create tag
5. Deploy
6. Create GitHub Release
**Time**: 30-45 minutes (excluding testing)
### Multi-Product Release (e.g., v1.0.0)
**Pre-release phase** (1 week before):
- Code freeze announced
- QA testing begins
- No new features merged
**Release phase** (2-3 days):
- Staging release (all products)
- QA validation
- Product owner sign-off
**Production phase** (1 day):
- Deploy in dependency order
- Smoke tests each product
- Monitor 24 hours
- User communication
**Time**: 5-7 days total, 4 hours active deployment
---
## 📞 Roles & Responsibilities
| Role | Responsibility |
|------|-----------------|
| **Developer** | Keep code release-ready, update versions |
| **QA** | Test staging releases, validate prod |
| **Release Engineer** | Create tags, manage deployment, monitor |
| **Product Owner** | Approve releases, communicate timeline |
| **DevOps** | Infrastructure ready, deployment scripts |
---
## 📊 Success Metrics
Track these per release:
- **Lead Time**: Time from code commit to production
- **Deployment Frequency**: How often you release
- **Change Failure Rate**: % of releases needing rollback
- **Time to Recovery**: Time to fix production issues
- **User Adoption**: % of users on latest version
---
## 📚 Related Documentation
- [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) - Mobile app releases
- [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) - Emergency procedures
- [../../RELEASE_STRATEGY.md](../../RELEASE_STRATEGY.md) - Original detailed guide
- [../../CHANGELOG.md](../../CHANGELOG.md) - Root version history
---
## ✅ Implementation Status
- ✅ Versioning strategy: SemVer
- ✅ Environments: dev, stage, prod
- ✅ Tag naming: Product-specific with brand prefix
- ✅ Product dependencies: Defined
- ✅ Release cadence: 3 levels
- ⏳ GitHub Actions: To be set up
- ⏳ Deployment automation: To be set up
---
**Next Step**: Review [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) for app-specific process.

727
docs/RELEASE/mobile-releases.md Normal file
View File

@@ -0,0 +1,727 @@
# Mobile App Release Process
**For Staff Mobile & Client Mobile Apps**
**Document Version**: 2.0
**Last Updated**: 2026-03-06
**Status**: ✅ Production Ready
---
## 📱 Overview
This document covers the complete release process for both mobile applications:
- **Staff Mobile App** (Worker Mobile) - `krow-withus-worker-mobile`
- **Client Mobile App** - `krow-withus-client-mobile`
Both apps:
- Built with Flutter
- Distributed via iOS App Store & Google Play Store
- Maintain independent versions
- Have independent CHANGELOGs
- Released via GitHub Actions workflows
---
## 📐 Versioning Strategy
### Semantic Versioning with Milestones
We use **Semantic Versioning 2.0.0** with milestone suffixes:
```
MAJOR.MINOR.PATCH-milestone
```
**Examples:**
- `0.0.1-m3` - Milestone 3 release
- `0.0.1-m4` - Milestone 4 release
- `1.0.0` - First production release (no suffix)
- `1.0.1` - Production patch release
**Version Rules:**
- **MAJOR**: Breaking changes, major architectural updates
- **MINOR**: New features, backward-compatible changes
- **PATCH**: Bug fixes, minor improvements
- **SUFFIX**: `-m3`, `-m4`, etc. for milestone tracking
### Version Location
Versions are defined in `pubspec.yaml`:
**Staff Mobile:** `apps/mobile/apps/staff/pubspec.yaml`
```yaml
version: 0.0.1-m4+1
```
**Client Mobile:** `apps/mobile/apps/client/pubspec.yaml`
```yaml
version: 0.0.1-m4+1
```
**Format:** `X.Y.Z-suffix+buildNumber`
- `0.0.1-m4` = version with milestone
- `+1` = build number (for app stores)
### Version Auto-Extraction
GitHub Actions workflows automatically extract the version from `pubspec.yaml` using `.github/scripts/extract-version.sh`. **No manual version input required.**
---
## 📝 CHANGELOG Management
### File Locations
- **Staff Mobile:** `apps/mobile/apps/staff/CHANGELOG.md`
- **Client Mobile:** `apps/mobile/apps/client/CHANGELOG.md`
### Format Standard
```markdown
# [App Name] - Change Log
## [v0.0.1-m4] - Milestone 4 - 2026-03-05
### Added - [Category Name]
- Feature description
- Another feature
### Fixed
- Bug fix description
### Changed
- Changed behavior
---
## [v0.0.1-m3] - Milestone 3 - 2026-02-15
### Added - [Category Name]
...
```
### Section Guidelines
Use these standard categories:
- **Added**: New features
- **Fixed**: Bug fixes
- **Changed**: Changes to existing functionality
- **Deprecated**: Soon-to-be removed features
- **Removed**: Removed features
- **Security**: Security fixes
### When to Update CHANGELOG
✅ **Update BEFORE release:**
- When milestone is complete
- Document all user-facing changes
- Include technical features if relevant
❌ **Don't document:**
- Internal refactoring (unless architecturally significant)
- Development-only changes
- Code formatting/linting
---
## 🏷️ Git Tag Format
### Tag Structure
```
krow-withus-<app>-mobile/<env>-v<version>
```
### Examples
**Staff Mobile (Worker):**
```
krow-withus-worker-mobile/dev-v0.0.1-m3
krow-withus-worker-mobile/stage-v0.0.1-m4
krow-withus-worker-mobile/prod-v1.0.0
```
**Client Mobile:**
```
krow-withus-client-mobile/dev-v0.0.1-m3
krow-withus-client-mobile/stage-v0.0.1-m4
krow-withus-client-mobile/prod-v1.0.0
```
### Tag Components
| Component | Values | Example |
|-----------|--------|---------|
| Product | `worker`, `client` | `worker` |
| Type | `mobile` | `mobile` |
| Environment | `dev`, `stage`, `prod` | `dev` |
| Version | From pubspec.yaml | `v0.0.1-m3` |
**Note:** Tags include the full version with milestone suffix (e.g., `v0.0.1-m4`, not just `v0.0.1`)
---
## 🚀 Release Workflows
### Release Types
We have **2 GitHub Actions workflows** for releases:
1. **Product Release** (`.github/workflows/product-release.yml`) - Standard releases
2. **Hotfix Branch Creation** (`.github/workflows/hotfix-branch-creation.yml`) - Emergency fixes
Both workflows use **manual triggers only** (`workflow_dispatch`) - no automatic releases.
---
## 📦 Standard Release Process
### Step 1: Prepare Release
1. **Ensure milestone is complete**
- All features implemented
- All tests passing
- Code reviews completed
2. **Update CHANGELOG**
```bash
# Edit the appropriate CHANGELOG file
vi apps/mobile/apps/staff/CHANGELOG.md
# OR
vi apps/mobile/apps/client/CHANGELOG.md
```
3. **Update version in pubspec.yaml**
```yaml
# apps/mobile/apps/staff/pubspec.yaml
version: 0.0.1-m4+1
```
4. **Commit changes**
```bash
git add apps/mobile/apps/staff/CHANGELOG.md apps/mobile/apps/staff/pubspec.yaml
git commit -m "docs(mobile): prepare staff app v0.0.1-m4 release"
git push origin dev
```
### Step 2: Trigger Release Workflow
1. **Navigate to GitHub Actions**
- Go to: https://github.com/Oloodi/krow-workforce/actions
- Select **"📦 Product Release"** workflow
2. **Click "Run workflow"**
3. **Select parameters:**
- **Branch**: `dev` (or release branch)
- **Product**: `worker-mobile-app` or `client-mobile-app`
- **Environment**: `dev`, `stage`, or `prod`
- **Pre-release**: Check if this is not a production release
4. **Click "Run workflow"**
### Step 3: Monitor Workflow
The workflow performs these steps automatically:
1. ✅ **Validate & Create Release** (Job 1)
- Extract version from pubspec.yaml
- Validate version format
- Generate tag name
- Create Git tag
- Extract release notes from CHANGELOG
- Create GitHub Release with formatted notes
2. 🔨 **Build Mobile Artifacts** (Job 2)
- Setup Node.js 20
- Install Firebase CLI
- Generate Data Connect SDK
- Setup Java 17
- Setup Flutter 3.38.x
- Bootstrap with Melos
- Decode keystore from secrets
- Build signed APK
- Verify APK signature
- Upload APK to GitHub Release
### Step 4: Verify Release
1. **Check GitHub Releases page**
- URL: https://github.com/Oloodi/krow-workforce/releases
- Verify release was created with correct tag
- Verify release notes display correctly
- Verify APK is attached (if applicable)
2. **Test the release**
- Download APK (dev releases)
- Install on test device
- Verify app launches and core features work
---
## 🔥 Hotfix Process
### When to Use Hotfix
✅ **Use hotfix for:**
- Critical bug in production affecting users
- Data loss or security vulnerability
- Service unavailable or major feature broken
- Customer-blocking issue
❌ **Don't use hotfix for:**
- Minor bugs (can wait for next release)
- Feature requests
- UI/UX improvements
- Styling issues
### Hotfix Workflow
1. **Navigate to GitHub Actions**
- Go to: https://github.com/Oloodi/krow-workforce/actions
- Select **"🚨 Product Hotfix - Create Branch"** workflow
2. **Click "Run workflow"**
3. **Fill in parameters:**
- **Product**: `worker-mobile-app` or `client-mobile-app`
- **Current Production Version**: e.g., `1.0.0` (without 'v' prefix)
- **Issue Description**: Brief description of the bug (used in CHANGELOG and branch name)
4. **The workflow automatically:**
- Creates hotfix branch: `hotfix/krow-withus-worker-mobile/prod-v1.0.1`
- Increments PATCH version: `1.0.0` → `1.0.1`
- Updates `pubspec.yaml` with new version
- Updates CHANGELOG.md with hotfix entry
- Creates Pull Request with hotfix instructions
5. **Fix the bug:**
```bash
# Checkout the hotfix branch
git fetch origin
git checkout hotfix/krow-withus-worker-mobile/prod-v1.0.1
# Make your fix
# ... edit files ...
# Test thoroughly
flutter test
# Commit your fix
git add .
git commit -m "fix(mobile): resolve critical production bug"
git push origin hotfix/krow-withus-worker-mobile/prod-v1.0.1
```
6. **Merge and Release:**
- Review and merge the Pull Request to `main` (or production branch)
- Trigger **Product Release** workflow with `prod` environment
- Workflow will create tag `krow-withus-worker-mobile/prod-v1.0.1`
- Deploy hotfix to production
7. **Backport to dev:**
```bash
git checkout dev
git merge hotfix/krow-withus-worker-mobile/prod-v1.0.1
git push origin dev
```
---
## 🔐 APK Signing Setup
### Overview
All Android builds require signing with keystores. We use **24 GitHub Secrets** (12 per app × 2 apps):
- 6 keystores (2 apps × 3 environments)
- 4 secrets per keystore (base64, password, alias, key password)
### Keystore Files
**Worker Mobile (Staff App):**
- `krow_with_us_staff_dev.jks` - ✅ Committed to repo
- `krow_staff_staging.jks` - ⚠️ Store in GitHub Secrets only
- `krow_staff_prod.jks` - ⚠️ Store in GitHub Secrets only
**Client Mobile:**
- `krow_with_us_client_dev.jks` - ✅ Committed to repo
- `krow_client_staging.jks` - ⚠️ Store in GitHub Secrets only
- `krow_client_prod.jks` - ⚠️ Store in GitHub Secrets only
### Required GitHub Secrets
#### Worker Mobile - 12 Secrets
**Dev Environment:**
- `WORKER_KEYSTORE_DEV_BASE64`
- `WORKER_KEYSTORE_PASSWORD_DEV`
- `WORKER_KEY_ALIAS_DEV`
- `WORKER_KEY_PASSWORD_DEV`
**Staging Environment:**
- `WORKER_KEYSTORE_STAGING_BASE64`
- `WORKER_KEYSTORE_PASSWORD_STAGING`
- `WORKER_KEY_ALIAS_STAGING`
- `WORKER_KEY_PASSWORD_STAGING`
**Production Environment:**
- `WORKER_KEYSTORE_PROD_BASE64`
- `WORKER_KEYSTORE_PASSWORD_PROD`
- `WORKER_KEY_ALIAS_PROD`
- `WORKER_KEY_PASSWORD_PROD`
#### Client Mobile - 12 Secrets
**Dev Environment:**
- `CLIENT_KEYSTORE_DEV_BASE64`
- `CLIENT_KEYSTORE_PASSWORD_DEV`
- `CLIENT_KEY_ALIAS_DEV`
- `CLIENT_KEY_PASSWORD_DEV`
**Staging Environment:**
- `CLIENT_KEYSTORE_STAGING_BASE64`
- `CLIENT_KEYSTORE_PASSWORD_STAGING`
- `CLIENT_KEY_ALIAS_STAGING`
- `CLIENT_KEY_PASSWORD_STAGING`
**Production Environment:**
- `CLIENT_KEYSTORE_PROD_BASE64`
- `CLIENT_KEYSTORE_PASSWORD_PROD`
- `CLIENT_KEY_ALIAS_PROD`
- `CLIENT_KEY_PASSWORD_PROD`
### Setup Using Helper Script
We provide an interactive script to configure all secrets:
```bash
.github/scripts/setup-mobile-github-secrets.sh
```
This script will:
1. Prompt for keystore file paths
2. Convert keystores to base64
3. Prompt for passwords and aliases
4. Display GitHub CLI commands to set secrets
5. Optionally execute the commands
### Manual Setup
If you prefer manual setup:
```bash
# 1. Convert keystore to base64
base64 -i /path/to/keystore.jks | pbcopy
# 2. Add to GitHub Secrets via web UI
# Go to: Repository → Settings → Secrets and variables → Actions
# Click "New repository secret"
# Name: WORKER_KEYSTORE_PROD_BASE64
# Value: Paste the base64 string
# 3. Repeat for all 24 secrets
```
Or use GitHub CLI:
```bash
# Set a secret using gh CLI
gh secret set WORKER_KEYSTORE_PROD_BASE64 < /path/to/keystore_base64.txt
# Set multiple secrets
gh secret set WORKER_KEYSTORE_PASSWORD_PROD -b "your_password"
gh secret set WORKER_KEY_ALIAS_PROD -b "your_alias"
gh secret set WORKER_KEY_PASSWORD_PROD -b "your_key_password"
```
### Verifying APK Signature
After build, the workflow automatically verifies the APK signature using:
```bash
.github/scripts/verify-apk-signature.sh <path-to-apk> <expected-alias>
```
---
## 📅 Release Cadence
### Development Releases (dev)
- **Frequency**: As needed (daily/weekly)
- **Purpose**: Test features, integration testing
- **Stability**: Unstable, may have bugs
- **Distribution**: Internal testing only
- **APK**: Signed with dev keystore
- **Tag example**: `krow-withus-worker-mobile/dev-v0.0.1-m3`
### Staging Releases (stage)
- **Frequency**: Bi-weekly (end of sprints)
- **Purpose**: QA testing, client demos
- **Stability**: Stable, feature-complete
- **Distribution**: QA team, stakeholders
- **APK**: Signed with staging keystore
- **Tag example**: `krow-withus-worker-mobile/stage-v0.0.1-m4`
### Production Releases (prod)
- **Frequency**: Monthly or milestone-based
- **Purpose**: Public release to app stores
- **Stability**: Production-grade, thoroughly tested
- **Distribution**: Public (App Store, Play Store)
- **APK**: Signed with production keystore
- **Tag example**: `krow-withus-worker-mobile/prod-v1.0.0`
---
## 🛠️ Helper Scripts Reference
All scripts are located in `.github/scripts/` and are used by workflows:
### 1. extract-version.sh
**Purpose**: Extract version from pubspec.yaml
**Usage**:
```bash
.github/scripts/extract-version.sh <path-to-pubspec.yaml>
```
**Example**:
```bash
VERSION=$(.github/scripts/extract-version.sh apps/mobile/apps/staff/pubspec.yaml)
echo $VERSION # Output: 0.0.1-m4
```
### 2. generate-tag-name.sh
**Purpose**: Generate consistent Git tag names
**Usage**:
```bash
.github/scripts/generate-tag-name.sh <app> <env> <version>
```
**Example**:
```bash
TAG=$(.github/scripts/generate-tag-name.sh worker dev 0.0.1-m4)
echo $TAG # Output: krow-withus-worker-mobile/dev-v0.0.1-m4
```
### 3. extract-release-notes.sh
**Purpose**: Extract CHANGELOG section for a specific version
**Usage**:
```bash
.github/scripts/extract-release-notes.sh <app> <env> <version> <tag>
```
**Example**:
```bash
NOTES=$(.github/scripts/extract-release-notes.sh worker dev 0.0.1-m4 krow-withus-worker-mobile/dev-v0.0.1-m4)
```
**Output format**:
```
**Environment:** DEV
**Tag:** krow-withus-worker-mobile/dev-v0.0.1-m4
## What is new in this release
[CHANGELOG content for v0.0.1-m4]
```
### 4. create-release-summary.sh
**Purpose**: Generate GitHub Step Summary with emojis
**Usage**:
```bash
.github/scripts/create-release-summary.sh <app> <env> <version> <tag>
```
**Creates**: Formatted summary in GitHub Actions UI
### 5. setup-apk-signing.sh
**Purpose**: Setup APK signing environment variables
**Usage** (in workflow):
```bash
.github/scripts/setup-apk-signing.sh <app> <env>
```
**What it does**:
- Decodes base64 keystore to file
- Sets `CM_KEYSTORE_PATH_<APP>` environment variable
- Sets keystore password, alias, and key password
### 6. verify-apk-signature.sh
**Purpose**: Verify APK is properly signed
**Usage**:
```bash
.github/scripts/verify-apk-signature.sh <apk-path> <expected-alias>
```
**Example**:
```bash
.github/scripts/verify-apk-signature.sh build/app/outputs/apk/release/app-release.apk androidreleasekey
```
### 7. attach-apk-to-release.sh
**Purpose**: Upload APK to existing GitHub Release
**Usage**:
```bash
.github/scripts/attach-apk-to-release.sh <tag> <apk-path> <app>
```
**Example**:
```bash
.github/scripts/attach-apk-to-release.sh krow-withus-worker-mobile/dev-v0.0.1-m4 build/app/outputs/apk/release/app-release.apk worker
```
### 8. setup-mobile-github-secrets.sh
**Purpose**: Interactive helper to configure all GitHub Secrets
**Usage**:
```bash
.github/scripts/setup-mobile-github-secrets.sh
```
**Interactive prompts for**:
- Keystore file paths
- Passwords and aliases
- Generates GitHub CLI commands
- Optionally executes commands
---
## 📋 Pre-Release Checklist
Before triggering a release, ensure:
### Code Quality
- [ ] All automated tests pass
- [ ] No critical linting errors
- [ ] Code review completed (for stage/prod)
- [ ] Security audit passed (for prod)
### Documentation
- [ ] CHANGELOG.md updated with all changes
- [ ] Version in pubspec.yaml matches CHANGELOG
- [ ] Breaking changes documented
- [ ] Migration guide created (if needed)
### Testing
- [ ] Feature testing completed
- [ ] Regression testing passed
- [ ] Performance testing acceptable
- [ ] Device compatibility verified
### Configuration
- [ ] Environment variables configured
- [ ] API endpoints correct for environment
- [ ] Feature flags set appropriately
- [ ] Analytics tracking verified
### GitHub Secrets (First-time setup)
- [ ] All 24 secrets configured
- [ ] Keystore passwords verified
- [ ] Test build succeeded with signing
---
## 🐛 Troubleshooting
### Workflow Fails: "Version not found in pubspec.yaml"
**Cause**: Invalid version format or missing version
**Solution**:
```yaml
# Ensure version line in pubspec.yaml looks like:
version: 0.0.1-m4+1
# Not:
version: 0.0.1 # Missing build number
version: "0.0.1-m4+1" # Don't quote the version
```
### Workflow Fails: "Secret not found"
**Cause**: Missing GitHub Secret
**Solution**:
1. Check secret name matches exactly (case-sensitive)
2. Run `.github/scripts/setup-mobile-github-secrets.sh`
3. Verify secrets at: Repository → Settings → Secrets and variables → Actions
### APK Signing Fails
**Cause**: Invalid keystore or wrong password
**Solution**:
1. Verify keystore base64 encoding: `base64 -i keystore.jks | base64 -d > test.jks`
2. Test password locally: `keytool -list -keystore test.jks`
3. Verify alias: `keytool -list -v -keystore test.jks | grep "Alias name"`
### CHANGELOG Not Extracted
**Cause**: Version format doesn't match in CHANGELOG
**Solution**:
```markdown
# CHANGELOG.md must have this EXACT format:
## [v0.0.1-m4] - Milestone 4 - 2026-03-05
# OR
## [0.0.1-m4] - Milestone 4 - 2026-03-05
# The script tries both [vX.Y.Z] and [X.Y.Z] formats
```
### Tag Already Exists
**Cause**: Trying to create a duplicate tag
**Solution**:
```bash
# Delete the existing tag (CAREFUL!)
git tag -d krow-withus-worker-mobile/dev-v0.0.1-m4
git push origin :refs/tags/krow-withus-worker-mobile/dev-v0.0.1-m4
# Then re-run the workflow
```
---
## 📚 Additional Resources
### Related Documentation
- [Agent Development Rules](../MOBILE/00-agent-development-rules.md)
- [Architecture Principles](../MOBILE/01-architecture-principles.md)
- [Mobile CI Workflow](../../.github/workflows/mobile-ci.yml)
### GitHub Actions Workflows
- **Product Release**: `.github/workflows/product-release.yml`
- **Hotfix Branch Creation**: `.github/workflows/hotfix-branch-creation.yml`
- **Mobile CI**: `.github/workflows/mobile-ci.yml`
### Useful Commands
```bash
# View current version
grep "^version:" apps/mobile/apps/staff/pubspec.yaml
# List all mobile tags
git tag -l "krow-withus-*-mobile/*"
# View latest releases
gh release list --limit 10
# Download APK from release
gh release download krow-withus-worker-mobile/dev-v0.0.1-m4 --pattern "*.apk"
```
---
## 🔄 Version History
| Version | Date | Changes |
|---------|------|---------|
| 2.0 | 2026-03-06 | Consolidated all release docs into single file |
| 1.0 | 2026-03-05 | Initial separate documentation files |
---
**Questions or Issues?**
Contact the DevOps team or create an issue in the repository.