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 (L24-L32)
Critical Policies (L58-L89)
Version Catalog Structure (L90-L121)
Bundle Patterns (L122-L153)
BOM Strategy (L154-L185)
References (L186-L196)
Related Rules (L197-L201)
Related Skills (L202-L209)

Available Resources

📚 references/ - Detailed documentation

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.

BOM Strategy

BOMs manage transitive dependency versions automatically:

// In root build.gradle
dependencyManagement {
    imports {
        mavenBom(libs.spring.boot.bom)
        mavenBom(libs.grpc.bom)
    }
}

Benefits

Automatic resolution: BOM handles all transitives
No conflicts: Related libraries stay compatible
Easy updates: Update BOM version once

Platform vs Enforce

// ✅ RECOMMENDED: Use platform() - allows version overrides if needed
implementation platform(libs.spring.boot.bom)

// ⚠️ AVOID: enforcedPlatform() - strictly forces versions
implementation enforcedPlatform(libs.spring.boot.bom)

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 |