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

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

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

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

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