Krow-workspace/.agents/skills/krow-mobile-release/SKILL.md

---
name: krow-mobile-release
description: KROW mobile app release process including versioning strategy, CHANGELOG management, GitHub Actions workflows, APK signing, Git tagging, and hotfix procedures. Use this when preparing mobile releases, updating CHANGELOGs, triggering release workflows, creating hotfix branches, troubleshooting release issues, or documenting release features. Covers both staff (worker) and client mobile products across dev/stage/prod environments.
---

# KROW Mobile Release Process

This skill defines the comprehensive release process for KROW mobile applications (staff and client). It covers versioning, changelog management, GitHub Actions automation, and hotfix procedures.

## When to Use This Skill

- Preparing for a mobile app release
- Updating CHANGELOG files with new features
- Triggering GitHub Actions release workflows
- Creating hotfix branches for production issues
- Understanding version numbering strategy
- Setting up APK signing secrets
- Troubleshooting release workflow failures
- Documenting release notes
- Managing release cadence (dev → stage → prod)

## Quick Reference

### Release Workflows
- **Product Release:** [GitHub Actions - Product Release](https://github.com/Oloodi/krow-workforce/actions/workflows/product-release.yml)
- **Hotfix Creation:** [GitHub Actions - Product Hotfix](https://github.com/Oloodi/krow-workforce/actions/workflows/hotfix-branch-creation.yml)

### Key Files
- **Staff CHANGELOG:** `apps/mobile/apps/staff/CHANGELOG.md`
- **Client CHANGELOG:** `apps/mobile/apps/client/CHANGELOG.md`
- **Staff Version:** `apps/mobile/apps/staff/pubspec.yaml`
- **Client Version:** `apps/mobile/apps/client/pubspec.yaml`

### Comprehensive Documentation
For complete details, see: [`docs/RELEASE/mobile-releases.md`](docs/RELEASE/mobile-releases.md) (900+ lines)

## 1. Versioning Strategy

### Format

```
v{major}.{minor}.{patch}-{milestone}
```

**Examples:**
- `v0.0.1-m4` - Milestone 4 release
- `v0.1.0-m5` - Minor version bump for Milestone 5
- `v1.0.0` - First production release (no milestone suffix)

### Semantic Versioning Rules

**Major (X.0.0):**
- Breaking changes
- Complete architecture overhaul
- Incompatible API changes

**Minor (0.X.0):**
- New features
- Backwards-compatible additions
- Milestone completions

**Patch (0.0.X):**
- Bug fixes
- Security patches
- Performance improvements

**Milestone Suffix:**
- `-m1`, `-m2`, `-m3`, `-m4`, etc.
- Indicates pre-production milestone phase
- Removed for production releases

### Version Location

Versions are defined in `pubspec.yaml`:

**Staff App:**
```yaml
# apps/mobile/apps/staff/pubspec.yaml
name: krow_staff_app
version: 0.0.1-m4+1  # version+build_number
```

**Client App:**
```yaml
# apps/mobile/apps/client/pubspec.yaml
name: krow_client_app
version: 0.0.1-m4+1
```

**Format:** `version+build`
- `version`: Semantic version with milestone (e.g., `0.0.1-m4`)
- `build`: Build number (increments with each build, e.g., `+1`, `+2`)

## 2. CHANGELOG Management

### Format

Each app maintains a separate CHANGELOG following [Keep a Changelog](https://keepachangelog.com/) format.

**Structure:**
```markdown
# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- New feature descriptions

### Changed
- Modified feature descriptions

### Fixed
- Bug fix descriptions

### Removed
- Removed feature descriptions

## [0.0.1-m4] - Milestone 4 - 2026-03-05

### Added
- Profile management with 13 subsections
- Documents & certificates management
- Benefits overview section
- Camera/gallery support for attire verification

### Changed
- Enhanced session management with auto token refresh

### Fixed
- Navigation fallback to home on invalid routes
```

### Section Guidelines

**[Unreleased]**
- Work in progress
- Features merged to dev but not released
- Updated continuously during development

**[Version] - Milestone X - Date**
- Released version
- Format: `[X.Y.Z-mN] - Milestone N - YYYY-MM-DD`
- Organized by change type (Added/Changed/Fixed/Removed)

### Change Type Definitions

**Added:**
- New features
- New UI screens
- New API integrations
- New user-facing capabilities

**Changed:**
- Modifications to existing features
- UI/UX improvements
- Performance enhancements
- Refactored code (if user-facing impact)

**Fixed:**
- Bug fixes
- Error handling improvements
- Crash fixes
- UI/UX issues resolved

**Removed:**
- Deprecated features
- Removed screens or capabilities
- Discontinued integrations

### Writing Guidelines

**✅ GOOD:**
```markdown
### Added
- Profile management with 13 subsections organized into onboarding, compliance, finances, and support categories
- Documents & certificates management with upload, status tracking, and expiry dates
- Camera and gallery support for attire verification with photo capture
- Benefits overview section displaying perks and company information
```

**❌ BAD:**
```markdown
### Added
- New stuff
- Fixed things
- Updated code
```

**Key Principles:**
- Be specific and descriptive
- Focus on user-facing changes
- Mention UI screens, features, or capabilities
- Avoid technical jargon users won't understand
- Group related changes together

### Updating CHANGELOG Workflow

**Step 1:** During development, add to `[Unreleased]`:
```markdown
## [Unreleased]

### Added
- New shift calendar view with month/week toggle
- Shift acceptance confirmation dialog

### Fixed
- Navigation crash when popping empty stack
```

**Step 2:** Before release, move to version section:
```markdown
## [0.1.0-m5] - Milestone 5 - 2026-03-15

### Added
- New shift calendar view with month/week toggle
- Shift acceptance confirmation dialog

### Fixed
- Navigation crash when popping empty stack

## [Unreleased]
<!-- Empty for next development cycle -->
```

**Step 3:** Update version in `pubspec.yaml`:
```yaml
version: 0.1.0-m5+1
```

## 3. Git Tagging Strategy

### Tag Format

```
krow-withus-<app>-mobile/<env>-vX.Y.Z
```

**Components:**
- `<app>`: `worker` (staff) or `client`
- `<env>`: `dev`, `stage`, or `prod`
- `vX.Y.Z`: Semantic version (from pubspec.yaml)

**Examples:**
```
krow-withus-worker-mobile/dev-v0.0.1-m4
krow-withus-worker-mobile/stage-v0.0.1-m4
krow-withus-worker-mobile/prod-v0.0.1-m4
krow-withus-client-mobile/dev-v0.0.1-m4
```

### Tag Creation

Tags are created automatically by GitHub Actions workflows. Manual tagging:

```bash
# Staff app - dev environment
git tag krow-withus-worker-mobile/dev-v0.0.1-m4
git push origin krow-withus-worker-mobile/dev-v0.0.1-m4

# Client app - prod environment
git tag krow-withus-client-mobile/prod-v1.0.0
git push origin krow-withus-client-mobile/prod-v1.0.0
```

### Tag Listing

```bash
# List all mobile tags
git tag -l "krow-withus-*-mobile/*"

# List staff app tags
git tag -l "krow-withus-worker-mobile/*"

# List production tags
git tag -l "krow-withus-*-mobile/prod-*"
```

## 4. GitHub Actions Workflows

### 4.1 Product Release Workflow

**File:** `.github/workflows/product-release.yml`

**Purpose:** Automated production releases with APK signing

**Trigger:** Manual dispatch via GitHub UI

**Inputs:**
- `app`: Select `worker` (staff) or `client`
- `environment`: Select `dev`, `stage`, or `prod`

**Process:**
1. ✅ Extracts version from `pubspec.yaml` automatically
2. ✅ Builds signed APKs for selected app
3. ✅ Creates GitHub release with CHANGELOG notes
4. ✅ Tags release (e.g., `krow-withus-worker-mobile/dev-v0.0.1-m4`)
5. ✅ Uploads APKs as release assets
6. ✅ Generates step summary with emojis

**Key Features:**
- **No manual version input** - reads from pubspec.yaml
- **APK signing** - uses GitHub Secrets for keystore
- **CHANGELOG extraction** - pulls release notes automatically
- **Visual feedback** - emojis in all steps

**Usage:**
```
1. Go to: GitHub Actions → "📦 Product Release"
2. Click "Run workflow"
3. Select app (worker/client)
4. Select environment (dev/stage/prod)
5. Click "Run workflow"
6. Wait for completion (~5-10 minutes)
```

**Release Naming:**
```
Krow With Us - Worker Product - DEV - v0.0.1-m4
Krow With Us - Client Product - PROD - v1.0.0
```

### 4.2 Product Hotfix Workflow

**File:** `.github/workflows/hotfix-branch-creation.yml`

**Purpose:** Emergency production fix automation

**Trigger:** Manual dispatch with version input

**Inputs:**
- `current_version`: Current production version (e.g., `0.0.1-m4`)
- `issue_description`: Brief description of the hotfix

**Process:**
1. ✅ Creates `hotfix/<version>` branch from latest production tag
2. ✅ Auto-increments PATCH version (e.g., `0.0.1-m4` → `0.0.2-m4`)
3. ✅ Updates `pubspec.yaml` with new version
4. ✅ Updates `CHANGELOG.md` with hotfix section
5. ✅ Creates PR back to main branch
6. ✅ Includes hotfix instructions in PR description

**Usage:**
```
1. Go to: GitHub Actions → "🚨 Product Hotfix - Create Branch"
2. Click "Run workflow"
3. Enter current production version (e.g., 0.0.1-m4)
4. Enter issue description (e.g., "critical crash on login")
5. Click "Run workflow"
6. Workflow creates branch and PR
7. Fix bug on hotfix branch
8. Merge PR to main
9. Use Product Release workflow to deploy
```

**Hotfix Branch Naming:**
```
hotfix/0.0.2-m4-critical-crash-on-login
```

### 4.3 Helper Scripts

**Location:** `.github/scripts/`

**Available Scripts:**
1. **extract-version.sh** - Extract version from pubspec.yaml
2. **generate-tag-name.sh** - Generate standardized tag names
3. **extract-release-notes.sh** - Extract CHANGELOG sections
4. **create-release-summary.sh** - Generate GitHub Step Summary with emojis

**Script Permissions:**
```bash
chmod +x .github/scripts/*.sh
```

**Usage Example:**
```bash
# Extract version from staff app
.github/scripts/extract-version.sh apps/mobile/apps/staff/pubspec.yaml

# Generate tag name
.github/scripts/generate-tag-name.sh worker dev 0.0.1-m4

# Extract release notes for version
.github/scripts/extract-release-notes.sh apps/mobile/apps/staff/CHANGELOG.md 0.0.1-m4
```

## 5. APK Signing Setup

### Required GitHub Secrets (24 Total)

**Per App (12 secrets each):**

**Staff (Worker) App:**
```
STAFF_UPLOAD_KEYSTORE_BASE64       # Base64-encoded keystore file
STAFF_UPLOAD_STORE_PASSWORD        # Keystore password
STAFF_UPLOAD_KEY_ALIAS             # Key alias
STAFF_UPLOAD_KEY_PASSWORD          # Key password
STAFF_KEYSTORE_PROPERTIES_BASE64   # Base64-encoded key.properties file
```

**Client App:**
```
CLIENT_UPLOAD_KEYSTORE_BASE64
CLIENT_UPLOAD_STORE_PASSWORD
CLIENT_UPLOAD_KEY_ALIAS
CLIENT_UPLOAD_KEY_PASSWORD
CLIENT_KEYSTORE_PROPERTIES_BASE64
```

### Generating Secrets

**Step 1: Create Keystore**

```bash
# For staff app
keytool -genkey -v \
  -keystore staff-upload-keystore.jks \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000 \
  -alias staff-upload

# For client app
keytool -genkey -v \
  -keystore client-upload-keystore.jks \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000 \
  -alias client-upload
```

**Step 2: Base64 Encode**

```bash
# Encode keystore
base64 -i staff-upload-keystore.jks | tr -d '\n' > staff-keystore.txt

# Encode key.properties
base64 -i key.properties | tr -d '\n' > key-props.txt
```

**Step 3: Add to GitHub Secrets**

```
Repository → Settings → Secrets and variables → Actions → New repository secret
```

Add each secret:
- Name: `STAFF_UPLOAD_KEYSTORE_BASE64`
- Value: Contents of `staff-keystore.txt`

Repeat for all 24 secrets.

### key.properties Format

```properties
storePassword=your_store_password
keyPassword=your_key_password
keyAlias=staff-upload
storeFile=../staff-upload-keystore.jks
```

## 6. Release Process (Step-by-Step)

### Standard Release (Dev/Stage/Prod)

**Step 1: Prepare CHANGELOG**

Update `CHANGELOG.md` with all changes since last release:
```markdown
## [0.1.0-m5] - Milestone 5 - 2026-03-15

### Added
- Shift calendar with month/week views
- Enhanced navigation with typed routes
- Profile completion wizard

### Fixed
- Session token refresh timing
- Navigation fallback logic
```

**Step 2: Update Version**

Edit `pubspec.yaml`:
```yaml
version: 0.1.0-m5+1  # Changed from 0.0.1-m4+1
```

**Step 3: Commit and Push**

```bash
git add apps/mobile/apps/staff/CHANGELOG.md
git add apps/mobile/apps/staff/pubspec.yaml
git commit -m "chore(staff): prepare v0.1.0-m5 release"
git push origin dev
```

**Step 4: Trigger Workflow**

1. Go to GitHub Actions → "📦 Product Release"
2. Click "Run workflow"
3. Select branch: `dev`
4. Select app: `worker` (or `client`)
5. Select environment: `dev` (or `stage`, `prod`)
6. Click "Run workflow"

**Step 5: Monitor Progress**

Watch workflow execution:
- ⏳ Version extraction
- ⏳ APK building
- ⏳ APK signing
- ⏳ GitHub Release creation
- ⏳ Tag creation
- ⏳ Asset upload

**Step 6: Verify Release**

1. Check GitHub Releases page
2. Download APK to verify
3. Install on test device
4. Verify version in app

### Hotfix Release

**Step 1: Identify Production Issue**

- Critical bug in production
- User-reported crash
- Security vulnerability

**Step 2: Trigger Hotfix Workflow**

1. Go to GitHub Actions → "🚨 Product Hotfix - Create Branch"
2. Click "Run workflow"
3. Enter current version: `0.0.1-m4`
4. Enter description: `Critical crash on login screen`
5. Click "Run workflow"

**Step 3: Review Created Branch**

Workflow creates:
- Branch: `hotfix/0.0.2-m4-critical-crash-on-login`
- PR to `main` branch
- Updated `pubspec.yaml`: `0.0.2-m4+1`
- Updated `CHANGELOG.md` with hotfix section

**Step 4: Fix Bug**

```bash
git checkout hotfix/0.0.2-m4-critical-crash-on-login

# Make fixes
# ... code changes ...

git add .
git commit -m "fix(auth): resolve crash on login screen"
git push origin hotfix/0.0.2-m4-critical-crash-on-login
```

**Step 5: Merge PR**

1. Review PR on GitHub
2. Approve and merge to `main`
3. Delete hotfix branch

**Step 6: Release to Production**

1. Use Product Release workflow
2. Select `main` branch
3. Select `prod` environment
4. Deploy hotfix

## 7. Release Cadence

### Development (dev)

- **Frequency:** Multiple times per day
- **Purpose:** Testing features in dev environment
- **Branch:** `dev`
- **Audience:** Internal development team
- **Approval:** Not required

### Staging (stage)

- **Frequency:** 1-2 times per week
- **Purpose:** QA testing, stakeholder demos
- **Branch:** `main`
- **Audience:** QA team, stakeholders
- **Approval:** Tech lead approval

### Production (prod)

- **Frequency:** Every 2-3 weeks (milestone completion)
- **Purpose:** End-user releases
- **Branch:** `main`
- **Audience:** All users
- **Approval:** Product owner + tech lead approval

### Milestone Releases

- **Frequency:** Every 2-4 weeks
- **Version Bump:** Minor version (e.g., `0.1.0-m5` → `0.2.0-m6`)
- **Process:**
  1. Complete all milestone features
  2. Update CHANGELOG with comprehensive release notes
  3. Deploy to stage for final QA
  4. After approval, deploy to prod
  5. Create GitHub release with milestone summary

## 8. Troubleshooting

### Workflow Fails: Version Extraction

**Error:** "Could not extract version from pubspec.yaml"

**Solutions:**
1. Verify `pubspec.yaml` exists at expected path
2. Check version format: `version: X.Y.Z-mN+B`
3. Ensure no extra spaces or tabs
4. Verify file is committed and pushed

### Workflow Fails: APK Signing

**Error:** "Keystore password incorrect"

**Solutions:**
1. Verify GitHub Secrets are set correctly
2. Re-generate and re-encode keystore
3. Check key.properties format
4. Ensure passwords don't contain special characters that need escaping

### Workflow Fails: CHANGELOG Extraction

**Error:** "Could not find version in CHANGELOG"

**Solutions:**
1. Verify CHANGELOG format matches: `## [X.Y.Z-mN] - Milestone N - YYYY-MM-DD`
2. Check square brackets are present
3. Ensure version matches pubspec.yaml
4. Add version section if missing

### Tag Already Exists

**Error:** "tag already exists"

**Solutions:**
1. Delete existing tag locally and remotely:
```bash
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
```
2. Re-run workflow

### Build Fails: Flutter Errors

**Error:** "flutter build failed"

**Solutions:**
1. Test build locally first:
```bash
cd apps/mobile/apps/staff
flutter build apk --release
```
2. Fix any analyzer errors
3. Ensure all dependencies are compatible
4. Clear build cache:
```bash
flutter clean
flutter pub get
```

## 9. Local Testing

Before triggering workflows, test builds locally:

### Building APKs Locally

**Staff App:**
```bash
cd apps/mobile/apps/staff
flutter clean
flutter pub get
flutter build apk --release
```

**Client App:**
```bash
cd apps/mobile/apps/client
flutter clean
flutter pub get
flutter build apk --release
```

### Testing Release Notes

Extract CHANGELOG section:
```bash
.github/scripts/extract-release-notes.sh \
  apps/mobile/apps/staff/CHANGELOG.md \
  0.0.1-m4
```

### Verifying Version

Extract version from pubspec:
```bash
.github/scripts/extract-version.sh \
  apps/mobile/apps/staff/pubspec.yaml
```

## 10. Best Practices

### CHANGELOG
- ✅ Update continuously during development
- ✅ Be specific and user-focused
- ✅ Group related changes
- ✅ Include UI/UX changes
- ❌ Don't include technical debt or refactoring (unless user-facing)
- ❌ Don't use vague descriptions

### Versioning
- ✅ Use semantic versioning strictly
- ✅ Increment patch for bug fixes
- ✅ Increment minor for new features
- ✅ Keep milestone suffix until production
- ❌ Don't skip versions
- ❌ Don't use arbitrary version numbers

### Git Tags
- ✅ Follow standard format
- ✅ Let workflow create tags automatically
- ✅ Keep tags synced with releases
- ❌ Don't create tags manually unless necessary
- ❌ Don't reuse deleted tags

### Workflows
- ✅ Test builds locally first
- ✅ Monitor workflow execution
- ✅ Verify release assets
- ✅ Test APK on device before announcing
- ❌ Don't trigger multiple workflows simultaneously
- ❌ Don't bypass approval process

## Summary

**Release Process Overview:**
1. Update CHANGELOG with changes
2. Update version in pubspec.yaml
3. Commit and push to appropriate branch
4. Trigger Product Release workflow
5. Monitor execution and verify release
6. Test APK on device
7. Announce to team/users

**Key Files:**
- `apps/mobile/apps/staff/CHANGELOG.md`
- `apps/mobile/apps/client/CHANGELOG.md`
- `apps/mobile/apps/staff/pubspec.yaml`
- `apps/mobile/apps/client/pubspec.yaml`

**Key Workflows:**
- Product Release (standard releases)
- Product Hotfix (emergency fixes)

**For Complete Details:**
See [`docs/RELEASE/mobile-releases.md`](docs/RELEASE/mobile-releases.md) - 900+ line comprehensive guide with:
- Detailed APK signing setup
- Complete troubleshooting guide
- All helper scripts documentation
- Release checklist
- Security best practices

When in doubt, refer to the comprehensive documentation or ask for clarification before releasing to production.