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

```yaml
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

```bash
# 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):

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

```bash
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
```bash
# 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

```bash
# 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