Best Practices for Version Management in Flutter

1. Manage All Versioning in pubspec.yaml

Flutter allows you to define both versionName and versionCode in one line:

version: 1.0.0+4

• 1.0.0 → versionName (Android) / CFBundleShortVersionString (iOS)
• +4 → versionCode (Android) / CFBundleVersion (iOS)

The versionCode must always increase.
Example: +3 → +4 → +5

The versionName can change freely, but versionCode must be strictly incremental for Google Play.

2. Do not store version information in local.properties

local.properties is an environment-specific file and should never be used for versioning.

sdk.dir=/Users/Username/Library/Android/sdk
flutter.sdk=/Users/Username/Developer/flutter

# ↓これらは削除/未記載にする（Flutterがpubspec.yamlから拾うため不要）
# flutter.buildMode=release
# flutter.versionName=1.0.0
# flutter.versionCode=3

local.properties should not be committed to Git and should contain only SDK paths.

3. Do not store version information in build.gradle

Flutter’s standard templates already reference flutter.versionCode and flutter.versionName.

defaultConfig {
    applicationId = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    minSdk = flutter.minSdkVersion
    targetSdk = flutter.targetSdkVersion
    versionCode = flutter.versionCode    // ← Flutterがpubspecから埋める
    versionName = flutter.versionName
}

4. Avoid using –build-number for every build

The recommended builds are simple:

flutter build appbundle --release

This automatically uses versions defined in pubspec.yaml.

This should only be used for temporary overrides.

flutter build appbundle --release --build-name 1.0.1 --build-number 4

5. Recommended Release Routine

Before every release to Google Play or App Store:

1. Update pubspec.yaml

version: 1.0.0+N   # Increase N by +1

2. Run a clean build:

flutter clean
flutter pub get
flutter build appbundle --release

3. Upload the AAB/IPA to the respective store.

6. Summary

Item	Best Practice
Version management location	pubspec.yaml (single source of truth)
versionCode	Increase every release (required by Google Play)
local.properties	Do NOT use for versioning
Build command	flutter build without extra flags