119 lines
3.7 KiB
Markdown
119 lines
3.7 KiB
Markdown
# 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.
|