Gradle Standards

Available Resources

📚 references/ - Detailed documentation

• cleanup workflow
• multi module
• native dependency locking
• optimization
• scope optimization
• troubleshooting
• unused detection
• version catalogs

Quick Start

1. Version Centralization (Required)

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

[versions]
spring-boot = "3.5.9"
grpc = "1.78.0"

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

2. Use in build.gradle

dependencies {
    // ✅ CORRECT: Use version catalog with explicit dependencies
    implementation libs.spring.boot.starter.web
    implementation libs.spring.boot.starter.actuator

    // ❌ NEVER: Hardcode versions
    // implementation "org.springframework.boot:spring-boot-starter-web:3.5.9"
}

Key Principles

Version Conflicts

All projects should preferably use the versions defined in the version catalog. When the resolved version doesn't match the catalog for some reason, prefer fixing the root cause:

1. First: Define the correct version in the version catalog and declare the dependency explicitly
2. Second: Use platform() to import a BOM that manages the version (e.g., Spring Boot dependencies)
3. Last resort: Use resolutionStrategy.force only for security-critical overrides where the above approaches don't work

// AVOID unless absolutely necessary for security
configurations.configureEach {
    resolutionStrategy {
        // Only for security-critical overrides as a last resort
        force libs.commons.compress  // CVE fix not yet in BOM
    }
}

References

Related Rules

Refer to the project's conductor/code_styleguides/ for established standards.

Dependency Resolution Stack

┌─────────────────────────────────────────────────────────────────────┐
│  1. VERSION CATALOG (libs.versions.toml)                            │
│     Single source of truth for declared versions                    │
├─────────────────────────────────────────────────────────────────────┤
│  2. RESOLUTION STRATEGY (build.gradle)                              │
│     Use Gradle's native resolutionStrategy for:                     │
│     - force() for security fixes                                    │
│     - eachDependency for group alignment                            │
│     - dependencySubstitution for module replacement                 │
├─────────────────────────────────────────────────────────────────────┤
│  3. LOCK FILE (gradle.lockfile)                                     │
│     Native Gradle locking (Gradle 9+ recommended)                   │
│     Captures EXACT resolved versions                                │
│                                                                     │
│  ⚠️  CRITICAL: Multi-module projects need lockfiles for ALL modules │
│     Use: ./gradlew resolveAndLockAll --write-locks                  │
│     NOT: ./gradlew dependencies --write-locks (root only!)          │
└─────────────────────────────────────────────────────────────────────┘

Lock File:

• Native locking - Built-in, no plugins, recommended for Gradle 9+

Multi-Module Lockfile Generation:

# ✅ CORRECT: Generates lockfiles for ALL submodules
./gradlew resolveAndLockAll --write-locks --refresh-dependencies --no-daemon --no-scan

# ❌ WRONG: Only generates for ROOT project
./gradlew dependencies --write-locks

# Verify coverage (lockfiles should ≈ build.gradle files)
find . -name "gradle.lockfile" | wc -l
find . -name "build.gradle" | wc -l

Related Skills