Version Management

Why Version Management Matters

A version number is a promise about compatibility. Trusting that promise — and managing it deliberately rather than reactively — is what makes a build reproducible: the same source checked out a year from now should still compile to the same behaviour, not silently pull in a different dependency graph. For the mechanics of how Maven actually resolves conflicting versions transitively, BOMs, and exclusions, see Dependencies Management — this page focuses on the versioning scheme itself and how to manage updates as a deliberate process rather than an accident.

Semantic Versioning (SemVer)

MAJOR.MINOR.PATCH is a contract, not just a counter — and the contract is only as good as the library maintainer's discipline in following it.

// 1 . 2 . 3
//   MAJOR.MINOR.PATCH

// MAJOR — incompatible API changes (a method removed, a signature changed,
//         a default behaviour flipped). Upgrading requires review.
// MINOR — new functionality, backward compatible. Existing code keeps working.
// PATCH — bug fixes only, backward compatible. Should always be safe.

Pre-release qualifiers and their ordering

1.0.0-alpha   // earliest, most unstable — internal testing
1.0.0-beta    // feature-complete, still finding bugs
1.0.0-RC1     // release candidate — believed ready, final verification
1.0.0         // final, stable release

// SemVer precedence: alpha < beta < rc < (no suffix = final)
// A SNAPSHOT sits conceptually before its corresponding release —
// 1.0.0-SNAPSHOT precedes 1.0.0 once it's actually released

SNAPSHOT vs Release — the Practical Difference

The detailed CI/CD mechanics of publishing SNAPSHOT vs release artifacts, and why builds containing a SNAPSHOT typically fail a release pipeline gate, are covered in What is Maven?.

Gradle Version Catalogs — Centralised, Type-Safe Versions

Maven centralises versions with <properties>; Gradle's modern equivalent is the version catalog — a single TOML file shared across every module in a multi-project build, with IDE autocomplete and compile-time checking of the references themselves.

// gradle/libs.versions.toml — one file, the single source of truth
[versions]
spring-boot = "3.2.0"
jackson     = "2.16.0"
junit       = "5.10.0"

[libraries]
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "spring-boot" }
jackson-databind        = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }
junit-jupiter           = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }

[bundles]
# group related libraries under one name, declared together everywhere they're used
testing = ["junit-jupiter"]

[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }

// build.gradle.kts — reference via the generated type-safe accessor 'libs'
dependencies {
    implementation(libs.spring.boot.starter.web)   // IDE autocompletes this — typo = compile error, not a runtime surprise
    implementation(libs.jackson.databind)
    testImplementation(libs.bundles.testing)
}

plugins {
    alias(libs.plugins.spring.boot)
}

A Practical Strategy for Staying Current

"Update dependencies regularly" is advice nobody disagrees with and almost nobody operationalises. Here's what it looks like as an actual process.

# Step 1 — see what's available, on a schedule (weekly/monthly), not reactively
mvn versions:display-dependency-updates
# or for Gradle:
./gradlew dependencyUpdates  # (com.github.ben-manes.versions plugin)

# Step 2 — patch releases: batch-update, low risk, run full test suite
mvn versions:use-latest-releases -DallowMajorUpdates=false -DallowMinorUpdates=false

# Step 3 — minor releases: update one at a time, read changelogs, run test suite
# Step 4 — major releases: NEVER batch. One major upgrade per PR, dedicated review,
#           explicit migration notes, and a rollback plan before merging

Interview Questions