Release Management Guide

This document explains the release process for Wellbeing Mapper, including both manual and automated approaches.

Release Approaches

When to Use:

How it Works:

  1. Create and push a version tag (e.g., v1.0.0)
  2. GitHub Actions automatically builds both Android and iOS
  3. Creates a GitHub release with all artifacts
  4. Includes automated testing and code analysis

Steps:

# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0

# GitHub Actions will automatically:
# 1. Run tests and analysis
# 2. Build Android APK and AAB (release)
# 3. Build iOS app (release, no-codesign)
# 4. Create GitHub release with artifacts

2. Manual Releases (For Testing and Quick Builds)

When to Use:

How it Works: Use the build-release.sh script which builds both platforms locally.

Steps:

# Make script executable (first time only)
chmod +x build-release.sh

# Run the release build script
./build-release.sh

Build Outputs

Android

iOS

Distribution Process

Android Distribution

  1. Build using either method above
  2. Upload app-release.aab to Google Play Console
  3. Follow Google Play’s release process

Direct APK Distribution

  1. Use the APK files from build/app/outputs/flutter-apk/
  2. Distribute directly to users (enable “Unknown Sources”)

iOS Distribution

App Store (Production)

  1. Build using either method above
  2. Open ios/Runner.xcworkspace in Xcode
  3. Archive the app (Product → Archive)
  4. Upload to App Store Connect via Xcode Organizer

TestFlight (Beta Testing)

  1. Same as App Store process
  2. After upload, enable TestFlight in App Store Connect
  3. Add beta testers

Release Checklist

Pre-Release

Release Process

Post-Release

Version Management

Version Format

Flutter uses the format: version: major.minor.patch+buildNumber

Ensuring Version Consistency

Important: Android builds use local.properties to override pubspec.yaml version information. Always sync versions before building.

Manual Process:

  1. Update pubspec.yaml version first
  2. Sync Android version info: ./sync-version.sh
  3. Commit the version change
  4. Create git tag matching the version
  5. Push both commit and tag

Example Workflow:

# 1. Update version in pubspec.yaml
# Change: version: 0.1.0+1
# To:     version: 1.0.0+1

# 2. Sync Android version information
./sync-version.sh

# 3. Commit version change (including updated local.properties)
git add pubspec.yaml gauteng-wellbeing-mapper-app/android/local.properties
git commit -m "Bump version to 1.0.0+1"

# 4. Create matching tag (without build number)
git tag v1.0.0

# 5. Push both
git push origin main
git push origin v1.0.0

Automated Version Checking: The GitHub Actions workflow now includes version validation to ensure consistency.

Version Synchronization Script (sync-version.sh)

Purpose: Ensures Android builds use the correct version by syncing local.properties with pubspec.yaml.

When to Use:

How it Works:

# Make executable (first time only)
chmod +x sync-version.sh

# Run the sync script
./sync-version.sh

What it Does:

  1. Reads version from pubspec.yaml (e.g., 1.1.1+2135)
  2. Extracts version name (1.1.1) and version code (2135)
  3. Updates android/local.properties with correct Flutter SDK paths and version info
  4. Ensures Android builds use the right version instead of cached values

Sample Output:

🔄 Syncing local.properties with pubspec.yaml version...
📋 Version information from pubspec.yaml:
   Full version: 1.1.1+2135
   Version name: 1.1.1
   Version code: 2135
🛠️ SDK paths:
   Flutter SDK: /Users/palmer/fvm/versions/3.27.1
   Android SDK: /Users/palmer/Library/Android/sdk
✅ local.properties updated successfully!

Version Checking Script

Use the included check-version.sh script to validate version consistency before releases:

# Check version consistency
./check-version.sh

# The script will:
# - Compare pubspec.yaml version with latest git tag
# - Provide guidance on next steps
# - Prevent accidental duplicate releases

Script Output Examples:

# First release (no tags exist)
🔍 Checking version consistency...
📄 pubspec.yaml version: 0.1.0
📋 No git tags found. This will be the first release.
✅ Ready to create tag: v0.1.0

# Ready for new release
✅ Versions are different - ready for new release!
📋 Suggested next steps:
   1. git add pubspec.yaml
   2. git commit -m 'Bump version to 1.0.0'
   3. git tag v1.0.0
   4. git push origin main
   5. git push origin v1.0.0

# Version needs updating
⚠️  Versions match current tag!
💡 If you want to create a new release, update the version in pubspec.yaml first

GitHub Actions Workflow

The automated workflow (.github/workflows/CD-deploy-github-releases.yml) includes:

  1. Code Quality Checks
    • Static analysis with flutter analyze
    • Unit tests with flutter test
  2. Multi-Platform Builds
    • Android: APK + App Bundle (release)
    • iOS: Release build (no code signing)
  3. Artifact Management
    • Uploads all build artifacts to GitHub release
    • Includes comprehensive release notes
  4. Requirements
    • Runs on macOS for iOS builds
    • Uses Flutter 3.27.1 to match local development
    • Requires GITHUB_TOKEN secret (automatically provided)

Troubleshooting

iOS Code Signing Issues

If you encounter code signing issues during manual builds:

  1. Ensure your development team is properly configured in Xcode
  2. Check that entitlements are properly linked (see TROUBLESHOOTING_GUIDE.md)
  3. Use the --no-codesign flag for CI builds

Android Build Issues

GitHub Actions Failures

Best Practices

  1. Always test release builds on physical devices before distribution
  2. Use semantic versioning for clear version communication
  3. Keep release notes updated for user transparency
  4. Test location permissions specifically as they’re critical for this app
  5. Use automated releases for production to ensure consistency
  6. Keep manual scripts for quick testing and development iterations

Quick Reference

# Sync Android version with pubspec.yaml
./sync-version.sh

# Check version consistency
./check-version.sh

# Local release build
./build-release.sh

# For USB testing on Android

# ensure adb is available
which adb || echo "install platform-tools: brew install android-platform-tools"

# see connected devices
adb devices

# install (replace with the actual apk path your build produced)
adb install -r build/app/outputs/flutter-apk/app-release.apk

# if you want to auto-grant runtime permissions
adb install -r -g build/app/outputs/flutter-apk/app-release.apk

# if the install fails due to signature/conflict, uninstall first (replace package name)
adb uninstall com.your.package.name
adb install -r build/app/outputs/flutter-apk/app-release.apk

# quick way to launch the app (replace package)
adb shell monkey -p com.your.package.name -c android.intent.category.LAUNCHER 1

# view runtime logs if something goes wrong
adb logcat --regex YourAppTagOrException

# Automated release (complete process)
# 1. Update version in pubspec.yaml
# 2. Sync Android version info
./sync-version.sh
# 3. Run version check
./check-version.sh
# 4. Commit and tag
git add pubspec.yaml gauteng-wellbeing-mapper-app/android/local.properties
git commit -m "Bump version to 1.0.0"
git tag v1.0.0
git push origin main
git push origin v1.0.0

# Test release build locally
flutter build apk --release
flutter build ios --release

# Clean build (if issues)
flutter clean && flutter pub get