# Release Process

This document describes how to cut a new release of **Motorcycle Digital Dashboard**.
The goal is a single, repeatable flow that keeps `pubspec.yaml`, `CHANGELOG.md`, and
the git tag in sync.

## Versioning Rules

We follow [Semantic Versioning 2.0.0](https://semver.org/) for the user-facing
`MAJOR.MINOR.PATCH` portion, and Flutter's `+BUILD` convention for the build number.

| Change type | Bump |
|---|---|
| Breaking change to UX, data model, or public API | `MAJOR` |
| Backwards-compatible feature, new screen, new sensor | `MINOR` |
| Bug fix, refactor, docs, lint cleanup, performance | `PATCH` |
| Every build uploaded to the store (Play Console / App Store Connect) | `+BUILD` |

The `+BUILD` counter **never resets** — it monotonically increases for the lifetime
of the app so the stores always see a newer `versionCode` / `CFBundleVersion`.

## Pre-Release Checklist

Before tagging a release, confirm:

- [ ] All work for the milestone is merged to `master`.
- [ ] CI is green on the latest commit of `master`.
- [ ] `flutter analyze` produces zero issues.
- [ ] `flutter test` passes locally.
- [ ] Any new permission, manifest, or Info.plist changes are documented in
      `CHANGELOG.md`.
- [ ] `flutter pub get` and `flutter pub outdated` have been run.

## Release Steps

1. **Update the version in `pubspec.yaml`:**
   ```yaml
   version: 1.1.0+2     # user-facing 1.1.0, build #2
   ```
   - Use the build number from the last store upload **+ 1** for `+BUILD`.

2. **Add a new section to `CHANGELOG.md`** above the previous release, dated
   `YYYY-MM-DD`. Use the existing `1.0.0` entry as a template. Move any
   in-progress items out of `[Unreleased]` into the new version section.

3. **Open a "Release" PR** titled e.g. `chore(release): 1.1.0`. Include both
   `pubspec.yaml` and `CHANGELOG.md` in the PR. Get a review and merge.

4. **Tag the merged commit** (from `master`):
   ```bash
   git checkout master
   git pull --tags
   git tag -a v1.1.0 -m "Release 1.1.0"
   git push origin v1.1.0
   ```
   - Use an **annotated** tag (`-a`) so the tag carries author, date, and message.
   - The tag name **must** be `vMAJOR.MINOR.PATCH` to match the changelog links
     and the `package_info_plus` lookup the in-app "About" screen may do later.

5. **Build & upload:**
   ```bash
   flutter build appbundle --release --build-name=1.1.0 --build-number=2
   ```
   The `--build-name` and `--build-number` flags are a safety net — they must
   match the values in `pubspec.yaml`. Upload the resulting `.aab` to the Play
   Console.

6. **Draft a GitHub release** from the tag, copy the changelog section into the
   release notes, and attach the `.aab` (or link to the Play Console listing).

## Hotfix / Patch Flow

For urgent fixes that can't wait for the next scheduled release:

1. Branch from the current `master` tag: `git checkout -b hotfix/1.0.1 v1.0.0`.
2. Land the fix, update `pubspec.yaml` to `1.0.1+3`, add a `1.0.1` section to
   `CHANGELOG.md`.
3. Merge back to `master`, tag `v1.0.1`, push the tag, build, upload.

## File Layout Owned by This Process

| File | Owned by release process |
|---|---|
| `pubspec.yaml` (`version:` line) | Yes |
| `CHANGELOG.md` | Yes |
| `git tag` (`v*`) | Yes |
| `lib/core/app_info.dart` | Yes (auto-mirrors `pubspec.yaml` — see file header) |

## Reference

- Flutter versioning docs: <https://docs.flutter.dev/deployment/android#versioning>
- Keep a Changelog 1.1.0: <https://keepachangelog.com/en/1.1.0/>
- Semantic Versioning 2.0.0: <https://semver.org/spec/v2.0.0.html>