Merge branch 'dev' into 493-implement-rapid-order-creation-voice-text-in-client-mobile-app
This commit is contained in:
Achintha Isuru
363
docs/RELEASE/APK_SIGNING_IMPLEMENTATION_SUMMARY.md
Normal file
363
docs/RELEASE/APK_SIGNING_IMPLEMENTATION_SUMMARY.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# 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
Normal file
282
docs/RELEASE/APK_SIGNING_SETUP.md
Normal file
@@ -0,0 +1,282 @@
|
||||
# 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
Normal file
115
docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# 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
Normal file
343
docs/RELEASE/HOTFIX_PROCESS.md
Normal file
@@ -0,0 +1,343 @@
|
||||
# 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
Normal file
564
docs/RELEASE/MOBILE_RELEASE_PLAN.md
Normal file
@@ -0,0 +1,564 @@
|
||||
# Mobile App Release Plan
|
||||
|
||||
**For Staff Mobile & Client Mobile Apps**
|
||||
|
||||
---
|
||||
|
||||
## 📱 Overview
|
||||
|
||||
This document covers release procedures for:
|
||||
|
||||
- **Staff Mobile App** (aka "Worker Mobile") - `krow-withus-worker-mobile`
|
||||
- **Client Mobile App** - `krow-withus-client-mobile`
|
||||
|
||||
Both apps:
|
||||
- Built with Flutter
|
||||
- Distributed to iOS & Android app stores
|
||||
- Maintain independent versions
|
||||
- Have independent CHANGELOGs
|
||||
- Share backend infrastructure
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ Tag & Release Naming
|
||||
|
||||
### Tag Format
|
||||
|
||||
```
|
||||
krow-withus-<app>-mobile/<environment>-v<major>.<minor>.<patch>
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
**Staff Mobile (Worker Mobile)**
|
||||
```
|
||||
krow-withus-worker-mobile/dev-v0.1.0
|
||||
krow-withus-worker-mobile/stage-v0.2.0
|
||||
krow-withus-worker-mobile/prod-v1.0.0
|
||||
krow-withus-worker-mobile/prod-v1.0.1-hotfix.1
|
||||
```
|
||||
|
||||
**Client Mobile**
|
||||
```
|
||||
krow-withus-client-mobile/dev-v0.1.0
|
||||
krow-withus-client-mobile/stage-v0.2.0
|
||||
krow-withus-client-mobile/prod-v1.0.0
|
||||
```
|
||||
|
||||
### GitHub Release Names
|
||||
|
||||
```
|
||||
Krow With Us - Worker Mobile - DEV - v0.1.0
|
||||
Krow With Us - Worker Mobile - STAGE - v0.2.0
|
||||
Krow With Us - Worker Mobile - PROD - v1.0.0
|
||||
|
||||
Krow With Us - Client Mobile - DEV - v0.1.0
|
||||
Krow With Us - Client Mobile - STAGE - v0.2.0
|
||||
Krow With Us - Client Mobile - PROD - v1.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 CHANGELOG Management
|
||||
|
||||
### Location
|
||||
|
||||
Each app has its own CHANGELOG in the `apps/mobile/` directory structure:
|
||||
|
||||
```
|
||||
apps/mobile/
|
||||
├── packages/
|
||||
│ ├── features/
|
||||
│ │ ├── staff/
|
||||
│ │ │ ├── authentication/CHANGELOG.md
|
||||
│ │ │ ├── home/CHANGELOG.md
|
||||
│ │ │ ├── payments/CHANGELOG.md
|
||||
│ │ │ ├── shifts/CHANGELOG.md
|
||||
│ │ │ └── ... (other staff features)
|
||||
│ │ └── client/
|
||||
│ │ ├── dashboard/CHANGELOG.md
|
||||
│ │ ├── orders/CHANGELOG.md
|
||||
│ │ └── ... (other client features)
|
||||
│ └── ... (other packages)
|
||||
├── apps/
|
||||
│ ├── staff_app/CHANGELOG.md ← Staff app root
|
||||
│ └── client_app/CHANGELOG.md ← Client app root
|
||||
└── CHANGELOG.md ← Consolidated (optional)
|
||||
```
|
||||
|
||||
### App-Level CHANGELOG Format
|
||||
|
||||
**File**: `apps/mobile/apps/staff_app/CHANGELOG.md`
|
||||
|
||||
```markdown
|
||||
# Staff Mobile App - Change Log
|
||||
|
||||
## [0.2.0] - 2026-03-15
|
||||
|
||||
### Added
|
||||
- Feature X implementation
|
||||
- Feature Y enhancement
|
||||
- New UI component Z
|
||||
|
||||
### Fixed
|
||||
- Bug fix for issue #123
|
||||
- Crash when loading payments
|
||||
|
||||
### Changed
|
||||
- Updated design system
|
||||
- Improved performance
|
||||
|
||||
### Deprecated
|
||||
- Removed old API endpoint
|
||||
|
||||
## [0.1.0] - 2026-03-01
|
||||
|
||||
### Added
|
||||
- Initial release
|
||||
- Authentication with phone & OTP
|
||||
- Shift browsing and booking
|
||||
- Clock in/out functionality
|
||||
- Payment history view
|
||||
```
|
||||
|
||||
### Consolidated CHANGELOG (Optional)
|
||||
|
||||
**File**: `apps/mobile/CHANGELOG.md` (at root of mobile folder)
|
||||
|
||||
High-level overview of both apps:
|
||||
|
||||
```markdown
|
||||
# Krow Workforce - Mobile Apps - Change Log
|
||||
|
||||
## Staff Mobile v0.2.0 + Client Mobile v0.1.0 - 2026-03-15
|
||||
|
||||
### Staff Mobile v0.2.0
|
||||
- Feature improvements
|
||||
- Bug fixes
|
||||
|
||||
### Client Mobile v0.1.0
|
||||
- Initial release
|
||||
|
||||
## Previous versions...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Version Files
|
||||
|
||||
### Staff Mobile App
|
||||
|
||||
**Primary Version File**: `apps/mobile/apps/staff_app/pubspec.yaml`
|
||||
|
||||
```yaml
|
||||
name: staff_app
|
||||
description: "Krow With Us - Staff App"
|
||||
|
||||
# Version format: MAJOR.MINOR.PATCH+BUILD_NUMBER
|
||||
version: 0.1.0+1
|
||||
|
||||
environment:
|
||||
sdk: '>=3.10.0 <4.0.0'
|
||||
flutter: '>=3.38.0 <4.0.0'
|
||||
```
|
||||
|
||||
**Rules**:
|
||||
- Update version before each release
|
||||
- Bump build number (+1) every build
|
||||
- SemVer only for version part (before +)
|
||||
|
||||
### Client Mobile App
|
||||
|
||||
**Primary Version File**: `apps/mobile/apps/client_app/pubspec.yaml`
|
||||
|
||||
```yaml
|
||||
name: client_app
|
||||
description: "Krow With Us - Client App"
|
||||
|
||||
version: 0.1.0+1
|
||||
|
||||
environment:
|
||||
sdk: '>=3.10.0 <4.0.0'
|
||||
flutter: '>=3.38.0 <4.0.0'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Release Workflow
|
||||
|
||||
### Step 1: Create Release Branch
|
||||
|
||||
```bash
|
||||
cd /Users/achintha/Documents/GitHub/krow-workforce
|
||||
|
||||
# For Staff Mobile
|
||||
git checkout -b release/staff-mobile-v0.2.0
|
||||
|
||||
# For Client Mobile
|
||||
git checkout -b release/client-mobile-v0.2.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Update Version Numbers
|
||||
|
||||
#### Staff Mobile Example (v0.1.0 → v0.2.0)
|
||||
|
||||
**File**: `apps/mobile/apps/staff_app/pubspec.yaml`
|
||||
|
||||
```yaml
|
||||
# Old
|
||||
version: 0.1.0+5
|
||||
|
||||
# New
|
||||
version: 0.2.0+6
|
||||
```
|
||||
|
||||
#### Client Mobile Example (v0.1.0 → v0.2.0)
|
||||
|
||||
**File**: `apps/mobile/apps/client_app/pubspec.yaml`
|
||||
|
||||
```yaml
|
||||
# Old
|
||||
version: 0.1.0+3
|
||||
|
||||
# New
|
||||
version: 0.2.0+4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Update CHANGELOG
|
||||
|
||||
**File**: `apps/mobile/apps/staff_app/CHANGELOG.md`
|
||||
|
||||
Add entry at **top**:
|
||||
|
||||
```markdown
|
||||
# Staff Mobile App - Change Log
|
||||
|
||||
## [0.2.0] - 2026-03-05
|
||||
|
||||
### Added
|
||||
- New shift details page with profile gating
|
||||
- Benefits overview section
|
||||
- Auto-match functionality
|
||||
|
||||
### Fixed
|
||||
- Payment history display bug
|
||||
- Clock-in location verification
|
||||
|
||||
### Changed
|
||||
- Updated design system components
|
||||
- Improved shift booking flow
|
||||
|
||||
## [0.1.0] - 2026-02-15
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Commit Changes
|
||||
|
||||
```bash
|
||||
cd /Users/achintha/Documents/GitHub/krow-workforce
|
||||
|
||||
# Stage changes
|
||||
git add apps/mobile/apps/staff_app/pubspec.yaml
|
||||
git add apps/mobile/apps/staff_app/CHANGELOG.md
|
||||
|
||||
# Commit
|
||||
git commit -m "chore(staff-mobile): bump version to 0.2.0
|
||||
|
||||
- Updated pubspec.yaml version: 0.1.0 → 0.2.0
|
||||
- Updated build number: 5 → 6
|
||||
- Updated CHANGELOG.md with v0.2.0 changes"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Create Pull Request
|
||||
|
||||
```bash
|
||||
# Push release branch
|
||||
git push origin release/staff-mobile-v0.2.0
|
||||
|
||||
# Create PR (GitHub CLI)
|
||||
gh pr create \
|
||||
--title "Release: Staff Mobile v0.2.0" \
|
||||
--body "## Release: Staff Mobile v0.2.0
|
||||
|
||||
### Changes
|
||||
- See CHANGELOG.md for full list
|
||||
|
||||
### Testing
|
||||
- [ ] All tests passing
|
||||
- [ ] Manual testing complete
|
||||
- [ ] CodeMagic build successful
|
||||
|
||||
### Checklist
|
||||
- [x] Version updated
|
||||
- [x] CHANGELOG updated
|
||||
- [x] Branch created from main
|
||||
- [ ] Approved by team lead"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 6: Merge to Main
|
||||
|
||||
Once PR is approved:
|
||||
|
||||
```bash
|
||||
# Switch to main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# Merge (fast-forward only)
|
||||
git merge --ff-only release/staff-mobile-v0.2.0
|
||||
|
||||
# Push to remote
|
||||
git push origin main
|
||||
|
||||
# Delete release branch
|
||||
git push origin --delete release/staff-mobile-v0.2.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 7: Create Git Tag
|
||||
|
||||
```bash
|
||||
# For DEV release
|
||||
git tag -a krow-withus-worker-mobile/dev-v0.2.0 \
|
||||
-m "Staff Mobile v0.2.0 - Dev Release
|
||||
|
||||
Features:
|
||||
- Shift details improvements
|
||||
- Benefits overview
|
||||
- Auto-match functionality
|
||||
|
||||
Testing:
|
||||
- All unit tests passing
|
||||
- Manual QA on dev environment"
|
||||
|
||||
# For STAGE release
|
||||
git tag -a krow-withus-worker-mobile/stage-v0.2.0 \
|
||||
-m "Staff Mobile v0.2.0 - Stage Release"
|
||||
|
||||
# For PROD release
|
||||
git tag -a krow-withus-worker-mobile/prod-v0.2.0 \
|
||||
-m "Staff Mobile v0.2.0 - Production Release"
|
||||
```
|
||||
|
||||
**Push tags**:
|
||||
|
||||
```bash
|
||||
git push origin krow-withus-worker-mobile/dev-v0.2.0
|
||||
git push origin krow-withus-worker-mobile/stage-v0.2.0
|
||||
git push origin krow-withus-worker-mobile/prod-v0.2.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 8: Create GitHub Release
|
||||
|
||||
1. Go to: GitHub → Releases → Draft a new release
|
||||
2. Fill in:
|
||||
|
||||
```
|
||||
Tag version: krow-withus-worker-mobile/dev-v0.2.0
|
||||
|
||||
Release title:
|
||||
Krow With Us - Worker Mobile - DEV - v0.2.0
|
||||
|
||||
Description:
|
||||
|
||||
## 🎯 What's New in v0.2.0
|
||||
|
||||
### ✨ Features
|
||||
- Shift details page with profile completion gating
|
||||
- Benefits overview with sick leave tracking
|
||||
- Auto-match shift recommendations
|
||||
|
||||
### 🔧 Improvements
|
||||
- Faster payment history loading
|
||||
- Better shift booking UX
|
||||
- Improved clock-in reliability
|
||||
|
||||
### 🐛 Bug Fixes
|
||||
- Fixed payment display date issue
|
||||
- Fixed location verification on iOS 15+
|
||||
- Fixed crash when no shifts available
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
**iOS**: Download via TestFlight (internal) or App Store
|
||||
**Android**: Download via Play Store
|
||||
|
||||
## 🔗 Dependencies
|
||||
|
||||
Requires:
|
||||
- Backend API v0.1.0+
|
||||
- DataConnect schema v0.3.0+
|
||||
|
||||
## ⚠️ Known Issues
|
||||
|
||||
- Location permissions take 5-10 seconds on first install
|
||||
- Workaround: Grant permissions in Settings app
|
||||
|
||||
## 📝 Notes for QA
|
||||
|
||||
- Test on actual device, not emulator
|
||||
- Verify clock-in with GPS enabled
|
||||
- Test all payment history edge cases
|
||||
|
||||
---
|
||||
|
||||
Release Date: 2026-03-05
|
||||
Build Number: 6
|
||||
```
|
||||
|
||||
3. **Optional**: Attach build artifacts (APK/AAB from CodeMagic)
|
||||
4. **Click**: "Publish release"
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Deployment Flow
|
||||
|
||||
### Dev Release → Staging
|
||||
|
||||
After dev is tested:
|
||||
|
||||
```bash
|
||||
# Create stage tag from same commit
|
||||
git tag -a krow-withus-worker-mobile/stage-v0.2.0 \
|
||||
krow-withus-worker-mobile/dev-v0.2.0 \
|
||||
-m "Staff Mobile v0.2.0 - Stage Release"
|
||||
|
||||
git push origin krow-withus-worker-mobile/stage-v0.2.0
|
||||
|
||||
# Deploy using CodeMagic or manual process
|
||||
```
|
||||
|
||||
### Staging Release → Production
|
||||
|
||||
After QA approval:
|
||||
|
||||
```bash
|
||||
# Create prod tag from same commit
|
||||
git tag -a krow-withus-worker-mobile/prod-v0.2.0 \
|
||||
krow-withus-worker-mobile/stage-v0.2.0 \
|
||||
-m "Worker Mobile v0.2.0 - Production Release"
|
||||
|
||||
git push origin krow-withus-worker-mobile/prod-v0.2.0
|
||||
|
||||
# Deploy to production
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📱 App Store Distribution
|
||||
|
||||
### iOS App Store
|
||||
|
||||
**Version Name**: Match pubspec.yaml version (0.2.0)
|
||||
**Build Number**: Match pubspec.yaml build number (+6)
|
||||
|
||||
**Steps**:
|
||||
1. Ensure TestFlight build passed
|
||||
2. Submit to App Review
|
||||
3. Apple reviews (3-5 days)
|
||||
4. Release to users (can be phased)
|
||||
|
||||
### Google Play Store
|
||||
|
||||
**Version Name**: Match pubspec.yaml version (0.2.0)
|
||||
**Version Code**: Match pubspec.yaml build number (6)
|
||||
|
||||
**Steps**:
|
||||
1. Upload APK/AAB from CodeMagic
|
||||
2. Fill in release notes (from CHANGELOG)
|
||||
3. Submit for review
|
||||
4. Google reviews (hours to 24h)
|
||||
5. Release to users (can be phased, e.g., 10% then 100%)
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Pre-Release Checklist
|
||||
|
||||
Before creating tags:
|
||||
|
||||
- [ ] All PRs merged to main
|
||||
- [ ] Code review complete
|
||||
- [ ] Tests passing (unit, widget, integration)
|
||||
- [ ] No lint/analysis errors: `flutter analyze`
|
||||
- [ ] Pubspec.yaml version updated
|
||||
- [ ] Build number incremented
|
||||
- [ ] CHANGELOG.md updated with date
|
||||
- [ ] Screenshots prepared (fresh)
|
||||
- [ ] Release notes drafted
|
||||
- [ ] No hardcoded strings (use translations)
|
||||
- [ ] No debug prints remaining
|
||||
- [ ] Performance acceptable (app launch < 3 seconds)
|
||||
- [ ] Screen lock/unlock works
|
||||
- [ ] Deep links tested
|
||||
- [ ] Notifications working
|
||||
- [ ] GPS/location working
|
||||
- [ ] Camera permissions working
|
||||
- [ ] All user-facing text reviewed
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Release Cadence
|
||||
|
||||
### Development Releases (dev)
|
||||
|
||||
- **Frequency**: Weekly
|
||||
- **Day**: Monday 10:00 UTC
|
||||
- **Process**: Quick, test in dev only
|
||||
|
||||
### Staging Releases (stage)
|
||||
|
||||
- **Frequency**: Bi-weekly (on sprint/feature completion)
|
||||
- **Day**: Wednesday before production
|
||||
- **Process**: Full QA testing, 1 week in staging
|
||||
|
||||
### Production Releases (prod)
|
||||
|
||||
- **Frequency**: Monthly (end of sprint)
|
||||
- **Day**: Sunday/Monday morning (low traffic)
|
||||
- **Process**: Full validation, market distribution
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related
|
||||
|
||||
- [OVERALL_RELEASE_PLAN.md](./OVERALL_RELEASE_PLAN.md) - General strategy
|
||||
- [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) - Emergency procedures
|
||||
- [../../CHANGELOG.md](../../CHANGELOG.md) - Root-level history
|
||||
|
||||
---
|
||||
|
||||
## 📞 Common Questions
|
||||
|
||||
**Q: What if I need to release just one app (not both)?**
|
||||
A: Completely fine! Each app is independent. Release when ready.
|
||||
|
||||
**Q: Do I need to update the root CHANGELOG?**
|
||||
A: Optional. If you do, keep it high-level and reference app-specific CHANGELOGs.
|
||||
|
||||
**Q: What about shared packages inside mobile/?**
|
||||
A: If shared package updated, mention in both app CHANGELOGs.
|
||||
|
||||
**Q: How do I handle breaking changes?**
|
||||
A: MAJOR version bump (0.x → 1.x) and clearly document in CHANGELOG.
|
||||
|
||||
**Q: Can I release dev and stage on different days?**
|
||||
A: Yes, no fixed schedule for dev/stage. Prod should be consistent (Sundays).
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-03-05
|
||||
**Owner**: Mobile Engineering Team
|
||||
**Status**: Active
|
||||
452
docs/RELEASE/OVERALL_RELEASE_PLAN.md
Normal file
452
docs/RELEASE/OVERALL_RELEASE_PLAN.md
Normal file
@@ -0,0 +1,452 @@
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user