# MotorSignal — Application Versioning & Release Management Guide

This document outlines the standard release and versioning procedures for the **MotorSignal** motorcycle digital dashboard and telemetry application.

---

## 1. Version Format

MotorSignal adheres strictly to **Semantic Versioning 2.0** combined with Flutter's build number scheme:

```text
MAJOR.MINOR.PATCH+BUILD
```

- **`MAJOR`**: Incompatible architecture overhauls, breaking database migrations, or fundamental UI paradigm shifts.
- **`MINOR`**: Significant new features, new screens, sensor integrations, or backward-compatible dashboard capabilities.
- **`PATCH`**: Bug fixes, crash fixes, sensor filter hardening, and performance optimizations.
- **`BUILD`**: Monotonically increasing integer incremented for every production binary (APK / AAB). **Never resets or decreases**.

### Historical & Current Baseline:
- **Baseline (Historical):** `1.0.0+100` (Git commit: `e700ca64`)
- **Previous Release:** `1.0.1+101` (Git commit: `f4d8883e`)
- **Current Release:** `1.0.2+102` (Git tag: `v1.0.2`)

---

## 2. Release Steps for Developers

Follow this 10-step protocol whenever cutting a new production release:

### Step 1: Choose the Next Semantic Version & Increment Build Number
Determine whether the change is a `PATCH` (e.g. `1.0.0` -> `1.0.1`), `MINOR` (e.g. `1.0.1` -> `1.1.0`), or `MAJOR` (e.g. `1.1.0` -> `2.0.0`).

Run the automated version bumper tool:
```bash
# To bump patch and increment build number (e.g. 1.0.0+100 -> 1.0.1+101):
dart run tool/bump_version.dart patch

# To bump minor (e.g. 1.0.1+101 -> 1.1.0+102):
dart run tool/bump_version.dart minor

# To bump major (e.g. 1.1.0+102 -> 2.0.0+103):
dart run tool/bump_version.dart major
```

### Step 2: Verify `pubspec.yaml`
Confirm that `pubspec.yaml` contains the new version:
```yaml
version: 1.0.1+101
```

### Step 3: Update `CHANGELOG.md`
Add a new release header following the Keep a Changelog standard:
```markdown
## [1.0.1] - 2026-08-29

### Fixed
- List fixed defects and stability improvements...

### Added
- List new capabilities...
```

### Step 4: Run Tests & Static Analysis
Verify that all unit tests, sensor simulations, and analysis checks pass:
```bash
flutter analyze lib/ test/
flutter test
```

### Step 5: Commit Version Bump
Commit the version changes:
```bash
git add pubspec.yaml CHANGELOG.md lib/core/app_info.dart lib/core/version/app_identity.dart
git commit -m "chore(release): bump version to 1.0.1+101"
```

### Step 6: Create Annotated Git Tag
Create a signed or annotated Git tag matching the semantic version:
```bash
git tag -a v1.0.1 -m "Release v1.0.1 (Build 101)"
```

### Step 7: Build Production Release APK
Compile the release binary with tree shaking:
```bash
flutter build apk --release
```

### Step 8: Create Release Manifest & Versioned Binary Artifact
Copy the output binary to the official versioned naming standard:
```bash
cp build/app/outputs/flutter-apk/app-release.apk MotorSignal-v1.0.1-build101-release.apk
```

Generate the machine-readable release manifest:
```json
{
  "application": "MotorSignal",
  "version": "1.0.1",
  "build": 101,
  "gitCommit": "f4d8883e2f7e868931413458bd22f213cfea10f4",
  "gitBranch": "master",
  "releaseChannel": "release",
  "telemetrySchema": 5,
  "exportSchema": 1,
  "buildTimestamp": "2026-08-29T22:35:00Z"
}
```

### Step 9: Verify On-Device Identity
Verify that:
1. The Settings screen displays `MotorSignal v1.0.1+101`.
2. Tapping the build footer opens the **Software Identity** modal displaying `Commit: f4d8883e...`.
3. Exporting a ride creates a `field_test_session.json` recording `version: 1.0.1` and `build: 101`.

### Step 10: Distribute
Upload `MotorSignal-v1.0.1-build101-release.apk` to phone mount for field validation.