| name | dependency-management |
| description | Version catalog strategy, dependency management, BOMs, and version constraints for Java/Gradle projects. Covers version centralization, never-downgrade policy, bundle patterns, resolution strategies, and compatibility matrices.
|
| compatibility | Java projects using Gradle 8.x or 9.x with version catalogs |
| metadata | {"version":"1.0.0","technology":"java","category":"build","tags":["java","gradle","dependencies","versions","bom"]} |
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
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.
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
Related Rules
Related Skills
