From 37d8427df9e241a3f43845b40bf653e614c573ef Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Fri, 6 Mar 2026 15:26:08 -0500 Subject: [PATCH] chore: remove overall release plan document and add mobile app release process documentation --- docs/MOBILE/00-agent-development-rules.md | 4 +- docs/MOBILE/01-architecture-principles.md | 4 +- docs/MOBILE/04-use-case-completion-audit.md | 41 +- docs/MOBILE/05-release-process.md | 64 ++ .../APK_SIGNING_IMPLEMENTATION_SUMMARY.md | 363 --------- docs/RELEASE/APK_SIGNING_SETUP.md | 282 ------- docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md | 115 --- docs/RELEASE/HOTFIX_PROCESS.md | 343 --------- docs/RELEASE/MOBILE_RELEASE_PLAN.md | 564 -------------- docs/RELEASE/OVERALL_RELEASE_PLAN.md | 452 ----------- docs/RELEASE/mobile-releases.md | 727 ++++++++++++++++++ 11 files changed, 818 insertions(+), 2141 deletions(-) create mode 100644 docs/MOBILE/05-release-process.md delete mode 100644 docs/RELEASE/APK_SIGNING_IMPLEMENTATION_SUMMARY.md delete mode 100644 docs/RELEASE/APK_SIGNING_SETUP.md delete mode 100644 docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md delete mode 100644 docs/RELEASE/HOTFIX_PROCESS.md delete mode 100644 docs/RELEASE/MOBILE_RELEASE_PLAN.md delete mode 100644 docs/RELEASE/OVERALL_RELEASE_PLAN.md create mode 100644 docs/RELEASE/mobile-releases.md diff --git a/docs/MOBILE/00-agent-development-rules.md b/docs/MOBILE/00-agent-development-rules.md index b28a9cb2..6049b64b 100644 --- a/docs/MOBILE/00-agent-development-rules.md +++ b/docs/MOBILE/00-agent-development-rules.md @@ -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: ` 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'?"). diff --git a/docs/MOBILE/01-architecture-principles.md b/docs/MOBILE/01-architecture-principles.md index 564df8e2..ae34bb58 100644 --- a/docs/MOBILE/01-architecture-principles.md +++ b/docs/MOBILE/01-architecture-principles.md @@ -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. diff --git a/docs/MOBILE/04-use-case-completion-audit.md b/docs/MOBILE/04-use-case-completion-audit.md index d17b86a0..5825311f 100644 --- a/docs/MOBILE/04-use-case-completion-audit.md +++ b/docs/MOBILE/04-use-case-completion-audit.md @@ -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) +**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) diff --git a/docs/MOBILE/05-release-process.md b/docs/MOBILE/05-release-process.md new file mode 100644 index 00000000..7749745b --- /dev/null +++ b/docs/MOBILE/05-release-process.md @@ -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--mobile/-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) diff --git a/docs/RELEASE/APK_SIGNING_IMPLEMENTATION_SUMMARY.md b/docs/RELEASE/APK_SIGNING_IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index 5aa49911..00000000 --- a/docs/RELEASE/APK_SIGNING_IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -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 diff --git a/docs/RELEASE/APK_SIGNING_SETUP.md b/docs/RELEASE/APK_SIGNING_SETUP.md deleted file mode 100644 index 6149937b..00000000 --- a/docs/RELEASE/APK_SIGNING_SETUP.md +++ /dev/null @@ -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! diff --git a/docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md b/docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md deleted file mode 100644 index b04eb3ad..00000000 --- a/docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md +++ /dev/null @@ -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) diff --git a/docs/RELEASE/HOTFIX_PROCESS.md b/docs/RELEASE/HOTFIX_PROCESS.md deleted file mode 100644 index 313b9be6..00000000 --- a/docs/RELEASE/HOTFIX_PROCESS.md +++ /dev/null @@ -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/-v` - ---- - -### 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) diff --git a/docs/RELEASE/MOBILE_RELEASE_PLAN.md b/docs/RELEASE/MOBILE_RELEASE_PLAN.md deleted file mode 100644 index c37dcc5b..00000000 --- a/docs/RELEASE/MOBILE_RELEASE_PLAN.md +++ /dev/null @@ -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--mobile/-v.. -``` - -### 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 diff --git a/docs/RELEASE/OVERALL_RELEASE_PLAN.md b/docs/RELEASE/OVERALL_RELEASE_PLAN.md deleted file mode 100644 index 9ef4785f..00000000 --- a/docs/RELEASE/OVERALL_RELEASE_PLAN.md +++ /dev/null @@ -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 - -``` -/-v.. -``` - -### 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 /-v -m "Release message"` -- [ ] Push tags: `git push origin ` -- [ ] 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 -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. - diff --git a/docs/RELEASE/mobile-releases.md b/docs/RELEASE/mobile-releases.md new file mode 100644 index 00000000..4403630c --- /dev/null +++ b/docs/RELEASE/mobile-releases.md @@ -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--mobile/-v +``` + +### 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 +``` + +--- + +## ๐Ÿ“… 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 +``` +**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 +``` +**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 +``` +**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 +``` +**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 +``` +**What it does**: +- Decodes base64 keystore to file +- Sets `CM_KEYSTORE_PATH_` 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 +``` +**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 +``` +**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.