SDKmuta/RELEASE_GUIDE.md

Release Guide - Shooting App

Overview

This guide explains how to create and publish a new release of the Shooting App. The app uses GitHub releases and semantic versioning for update management.

Current Setup

• Repository: https://github.com/Bl3kiiie/shooting_app
• Update Method: Manual check via Settings button (no automatic prompts)
• Version File: pubspec.yaml
• Update Detection: Compares app version with GitHub release tags

---

Step-by-Step Release Process

1. Update Version in pubspec.yaml

Open pubspec.yaml and update the version number:

version: 1.0.2+2

Format: MAJOR.MINOR.PATCH+BUILD_NUMBER

Examples:

• 1.0.1+1 → 1.0.2+1 (patch release, new build)
• 1.0.2+1 → 1.0.2+2 (same version, new build)
• 1.0.2+2 → 1.1.0+1 (minor release)

Important: New tag must be HIGHER than previous version for users to see update prompt.

2. Build Release APK

# Navigate to project directory
cd /home/bl3kunja/Documents/Programming/Strelišče/shooting_app

# Build release APK
flutter build apk --release

The APK will be generated at: build/app/outputs/flutter-app/release/app-release.apk

3. Create GitHub Release (Option A: Web Interface - Recommended)

1. Go to: https://github.com/Bl3kiiie/shooting_app/releases

2. Click Draft a new release or Create a new release

3. Fill in the form:

   Tag version: v1.0.2 (must match your new version number)

   Release title: e.g., Version 1.0.2 - Bug Fixes and Improvements

   Description (example):

   ## Changes in v1.0.2
   - Fixed camera calibration issue
   - Improved bullet detection accuracy
   - Added German language support
   - Performance optimizations
   
   ## Installation
   Download the APK from the assets below and install on your device.
   

4. Upload APK:

   • Click "Attach binaries by dropping them here or selecting them"
   • Select: build/app/outputs/flutter-app/release/app-release.apk

5. Click Publish release

3. Create GitHub Release (Option B: Command Line)

If using GitHub CLI (gh command):

# Create tag locally
git tag v1.0.2

# Push tag to GitHub
git push origin v1.0.2

# Create release (interactive)
gh release create v1.0.2 \
  --title "Version 1.0.2" \
  --notes "Your changelog here"

# Upload APK to release
gh release upload v1.0.2 build/app/outputs/flutter-app/release/app-release.apk

4. Commit Version Update (Optional)

If you want to track version changes in git:

git add pubspec.yaml
git commit -m "bump version to 1.0.2+2"
git push origin main

---

How Users Update

1. User opens app → Settings screen
2. User taps "Check for Updates" button
3. App compares:
   • Current version: 1.0.1+1
   • Latest GitHub release tag: v1.0.2
4. Since v1.0.2 > v1.0.1, update is available
5. Dialog shows "Update Available"
6. User clicks "Update" → Opens GitHub release page
7. User downloads and installs new APK

---

Important Notes

Version Numbering

• Always increment version number before creating release
• Tag format: vX.Y.Z (e.g., v1.0.2, v1.1.0)
• App checks: tag_version > app_version

GitHub Token

• Stored in: lib/services/update_checker.dart
• Token: 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
• Scopes: repo (for private repo access)
• Consider rotating this token periodically for security

Testing Before Release

# Test the build
flutter build apk --release

# Verify APK was created
ls -lh build/app/outputs/flutter-app/release/app-release.apk

# Optionally install on connected device
flutter install build/app/outputs/flutter-app/release/app-release.apk

Troubleshooting Update Detection

If users don't see update prompt:

1. Check GitHub release exists: https://github.com/Bl3kiiie/shooting_app/releases
2. Verify tag format is vX.Y.Z (must start with 'v')
3. Confirm new version > current version
4. User must tap "Check for Updates" manually
5. Check app logs for errors

---

Checklist for Next Release

• Update version in pubspec.yaml
• Test build: flutter build apk --release
• Create GitHub release with tag vX.Y.Z
• Upload APK to release
• Write changelog/description
• Publish release
• (Optional) Test update detection in app

---

Example Release Workflow

# 1. Update version in pubspec.yaml (manually edit to 1.0.2+1)

# 2. Build APK
flutter build apk --release

# 3. Create tag and push
git tag v1.0.2
git push origin v1.0.2

# 4. Create release via GitHub web:
# - Go to https://github.com/Bl3kiiie/shooting_app/releases
# - Draft new release
# - Tag: v1.0.2
# - Upload APK from build/app/outputs/flutter-app/release/app-release.apk
# - Publish

# 5. Users can now "Check for Updates" and see the new version

---

Files Referenced

• pubspec.yaml - Version number
• lib/services/update_checker.dart - GitHub token and update logic
• lib/screens/settings_screen.dart - "Check for Updates" button
• lib/utils/translations.dart - Update dialog translations

---

Last Updated: November 13, 2025 Current Version: 1.0.1 Next Planned Version: 1.0.2