What is Semantic Versioning Guide

Overview

Semantic Versioning (SemVer) is a versioning standard that communicates the nature of changes in a software release through a structured version number.

Format

textCopy
MAJOR.MINOR.PATCH

Example: 2.4.1

1.x.x → 2.0.0

1.2.x → 1.3.0

1.2.3 → 1.2.4

Rules

textCopy
1.0.0 — Initial stable release
1.0.1 — Bug fix
1.1.0 — New feature added (backward-compatible)
1.1.1 — Bug fix on the new feature
2.0.0 — Breaking change (API changed incompatibly)

Pre-release & Build Metadata

textCopy
1.0.0-alpha           → Alpha release
1.0.0-alpha.1         → Alpha iteration
1.0.0-beta.2          → Beta release
1.0.0-rc.1            → Release candidate
1.0.0+build.123       → Build metadata (doesn't affect precedence)

In Flutter — pubspec.yaml

yamlCopy
# Your app version
version: 1.2.3+45
#         ↑   ↑
#         |   build number (Android versionCode, iOS CFBundleVersion)
#         semantic version (shown to users)

# Dependency version constraints
dependencies:
  http: ^1.2.0      # >= 1.2.0 and < 2.0.0 (compatible with 1.x)
  dio: ">=5.0.0 <6.0.0"  # explicit range
  path: any         # any version (not recommended)

Caret (^) Constraint

yamlCopy
^1.2.3   # means >=1.2.3 <2.0.0
^0.2.3   # means >=0.2.3 <0.3.0  (special case for 0.x — minor is locked)
^0.0.3   # means >=0.0.3 <0.0.4  (special case for 0.0.x — patch is locked)

When to Use Which Version Bump

1.2.3 → 1.2.4

1.2.3 → 1.3.0

1.2.3 → 2.0.0

1.2.3 → 2.0.0

1.2.3 → 1.2.4

1.2.3 → 1.3.0

Flutter App vs Package Versioning

version: 1.2.3+45

1.2.3

45

version: 1.2.3

Reference: semver.org is the official guide. Dart/pub follows SemVer strictly for packages.