Dependency Management

Standards for managing library versions, dependency constraints, and Bill of Materials (BOM) in Java/Gradle projects.

When to use this skill

• Adding or updating dependencies

• Managing library versions in version catalogs

• Resolving dependency conflicts

• Upgrading Spring Boot or other frameworks

• Setting up BOM-based dependency management

• Understanding version compatibility matrices

Skill Contents

Sections

• When to use this skill

• Critical Policies

• Version Catalog Structure

• Bundle Patterns

• Platform Dependency Management

• References

• Related Rules

• Related Skills

Available Resources

📚 references/ - Detailed documentation

• bom strategy

• bundle patterns

• compatibility matrices

• resolution strategies

• security updates

• version centralization

Critical Policies

1. Version Centralization (Mandatory)

All dependency versions MUST be centralized in gradle/libs.versions.toml .

// ❌ NEVER: Hardcode versions in build.gradle dependencies { implementation "org.springframework.boot:spring-boot-starter-web:3.5.9" }

// ✅ ALWAYS: Use version catalog dependencies { implementation libs.spring.boot.starter.web }

See references/version-centralization.md for anti-patterns and approved locations.

2. Never Downgrade Pre-existing Versions

Never replace a library version with an older version that pre-existed in the repository.

Allowed Not Allowed

Upgrade a library Downgrade a pre-existing version

Adjust a version YOUR PR introduced Pin BOM-managed dependency lower

Add warning comment Remove security patches

See references/version-centralization.md for the full policy.

Version Catalog Structure

The version catalog (gradle/libs.versions.toml ) is the single source of truth:

[versions] spring-boot = "3.5.9" grpc = "1.78.0" spock = "2.4-groovy-4.0" junit-jupiter = "5.14.2"

[libraries] spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "spring-boot" } spring-boot-bom = { module = "org.springframework.boot:spring-boot-dependencies", version.ref = "spring-boot" }

[bundles] testing-spock = ["spock-core", "spock-spring"] spring-boot-service = ["spring-boot-starter-web", "spring-boot-starter-actuator"]

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

Key Principles

Principle Description

Single Source All versions in one file

BOMs First Use BOMs for transitive management

Type-Safe Gradle generates type-safe accessors

Semantic Groups Organize by framework/purpose

Bundle Patterns

Bundles group related dependencies for cleaner build files:

// ❌ Verbose: Multiple declarations dependencies { testImplementation libs.spock.core testImplementation libs.spock.spring testImplementation libs.testcontainers.spock testImplementation libs.testcontainers.postgresql }

// ✅ Clean: Use bundles dependencies { testImplementation libs.bundles.testing.spock testImplementation libs.bundles.testing.integration }

Common Bundles

Bundle Contents Use Case

testing-spock

spock-core, spock-spring Most test suites

testing-integration

testcontainers-spock, postgres Integration tests

spring-boot-service

web, actuator Web services

grpc-core

netty-shaded, protobuf, stub gRPC services

codegen

lombok, mapstruct Code generation

See references/bundle-patterns.md for all bundles and usage.

Platform Dependency Management

Use Gradle's native platform() to import BOMs. The io.spring.dependency-management plugin is also used in Spring Boot projects (it is applied automatically by the Spring Boot plugin), but when importing additional BOMs prefer platform() over mavenBom directives.

dependencies { // Use platform() to import managed versions from BOMs implementation platform(libs.spring.boot.bom) implementation platform(libs.grpc.bom)

// Dependencies managed by the platform don't need explicit versions
implementation libs.spring.boot.starter.web
implementation libs.spring.boot.starter.actuator

}

Key Rules

• Use platform() to import BOMs, never enforcedPlatform() (prevents necessary overrides)

• Prefer platform() over mavenBom directives for BOM imports -- platform() is the native Gradle approach

• The io.spring.dependency-management plugin is applied automatically by the Spring Boot plugin and manages many versions; additional BOMs should be imported via platform()

• platform() allows overriding when needed (e.g., for security patches)

See references/bom-strategy.md for complete patterns.

References

Reference Description

version-centralization.md Core principles, anti-patterns, policies

bundle-patterns.md All bundle definitions and usage

bom-strategy.md Bill of Materials setup

compatibility-matrices.md Java/Spring/testing version tables

resolution-strategies.md Conflict resolution, substitutions

security-updates.md CVE fixes, forced versions

Related Rules

• java-versions-and-dependencies - Original comprehensive rule

• java-gradle-best-practices - Gradle configuration patterns

Related Skills

Skill Purpose

gradle-standards Gradle build configuration

fix-vulnerabilities Vulnerability management

upgrade-gradle-9 Gradle 9 migration

upgrade-java-25 Java 25 compatibility