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

name, description

name

description

krow-mobile-release

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
• Hotfix Creation: GitHub Actions - Product Hotfix

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 (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:

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

Client App:

# 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 format.

Structure:

# 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:

### 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:

### 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]:

## [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:

## [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:

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:

# 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

# 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:

chmod +x .github/scripts/*.sh

Usage Example:

# 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

# 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

# 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

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:

## [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:

version: 0.1.0-m5+1  # Changed from 0.0.1-m4+1

Step 3: Commit and Push

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

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:

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:

cd apps/mobile/apps/staff
flutter build apk --release

2. Fix any analyzer errors
3. Ensure all dependencies are compatible
4. Clear build cache:

flutter clean
flutter pub get

9. Local Testing

Before triggering workflows, test builds locally:

Building APKs Locally

Staff App:

cd apps/mobile/apps/staff
flutter clean
flutter pub get
flutter build apk --release

Client App:

cd apps/mobile/apps/client
flutter clean
flutter pub get
flutter build apk --release

Testing Release Notes

Extract CHANGELOG section:

.github/scripts/extract-release-notes.sh \
  apps/mobile/apps/staff/CHANGELOG.md \
  0.0.1-m4

Verifying Version

Extract version from pubspec:

.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 - 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.