3.7 KiB

Raw Blame History

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:

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:

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

version: 1.0.1+101

Step 3: Update `CHANGELOG.md`

Add a new release header following the Keep a Changelog standard:

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

flutter analyze lib/ test/
flutter test

Step 5: Commit Version Bump

Commit the version changes:

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:

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:

flutter build apk --release

Step 8: Create Release Manifest & Versioned Binary Artifact

Copy the output binary to the official versioned naming standard:

cp build/app/outputs/flutter-apk/app-release.apk MotorSignal-v1.0.1-build101-release.apk

Generate the machine-readable release manifest:

{
  "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:

The Settings screen displays MotorSignal v1.0.1+101.
Tapping the build footer opens the Software Identity modal displaying Commit: f4d8883e....
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.

3.7 KiB Raw Blame History