werkator/docs/adrs/0002-2026-06-09.gradle-version.md

Gradle Version

Status:

• proposed: 2026-06-09
• accepted: -
• rejected: -
• superseded: -

Decision [proposed]: Gradle 8.14 — minimum required by Spring Boot 4.0; Gradle 9 deferred until openapi-generator and ktlint-gradle confirm compatibility.

Context and Problem Statement

GitTally is a greenfield Kotlin/Spring Boot project. A Gradle version must be chosen for the initial setup.

Gradle 9 (currently 9.5.1) is now stable and available. The question is whether it is the right choice at project start, or whether staying on Gradle 8.x is safer.

Technical Background

Configuration Cache is a Gradle feature that serializes the result of the configuration phase (evaluating all build scripts, resolving plugins, building the task graph) so that subsequent builds can skip it entirely. In large projects the configuration phase alone can take tens of seconds; caching it makes every incremental build substantially faster. In Gradle 8.x Configuration Cache is opt-in. In Gradle 9 it is stable and mandatory: any plugin that reads mutable environment state or modifies the project model after configuration will fail hard rather than emit a warning. This enforcement fixed longstanding correctness issues across the ecosystem, but it also means any plugin that has not been updated will break the build outright.

The Gradle version choice is not isolated to the build tool itself. It has a direct dependency chain:

• Gradle 9 is officially supported by Spring Boot 4.0 only. Spring Boot 4.0 also requires Gradle 8.14 as a minimum for the 8.x line.
• Spring Boot 4.0 requires Spring Framework 7 and Jakarta EE 11 — a generation step up from Spring Boot 3.x (Spring Framework 6, Jakarta EE 10).
• Plugin ecosystem readiness varies: the openapi-generator Gradle plugin has a known Gradle 9 issue in its generated build files, and ktlint-gradle 12.1.1 Gradle 9 support needs verification.
• The io.spring.dependency-management plugin used to resolve the Spring BOM has known friction with Gradle 9 and would need to be replaced by a native platform() import.

The Spring Boot version decision (ADR 0003) concluded that Spring Boot 4.0 is required. Spring Boot 4.0 mandates Gradle 8.14 as minimum, meaning a wrapper upgrade from the current 8.8 is necessary regardless of whether Gradle 9 is chosen.

Considered Options

• Gradle 8.14 (minimum for Spring Boot 4.0)
• Gradle 9.x

Gradle 8.x

The currently configured series (wrapper at 8.8, to be bumped to 8.14+ for Spring Boot 4.0).

Advantages

• Plugin compatibility is well understood for ktlint-gradle and openapi-generator-gradle-plugin.
• Configuration Cache is opt-in — teams can enable it incrementally and diagnose failures without blocking the build.
• Lower risk for adopting spec-first OpenAPI: the openapi-generator-gradle-plugin has a known Gradle 9 incompatibility in generated build files.

Disadvantages

• Not on the current Gradle major line; the Configuration Cache benefits are not enforced.
• An eventual migration to Gradle 9 will still be needed.

Gradle 9.x

The current major release (9.5.1 as of May 2026), officially supported alongside Spring Boot 4.0.

Advantages

• Aligns with the latest Spring Boot generation in a fully supported pairing.
• Configuration Cache is mandatory: faster incremental builds and build-script correctness is enforced across the whole plugin chain — problems surface immediately rather than silently.
• io.spring.dependency-management plugin is replaced by cleaner native platform() BOM import.
• Greenfield is the easiest moment to adopt it; no migration debt later.

Disadvantages

• openapi-generator-gradle-plugin has a known Gradle 9 issue in generated build.gradle files; impact on the spec-first code generation task specifically needs verification.
• ktlint-gradle 12.1.1 Gradle 9 support needs verification.
• Configuration Cache mandatory means any currently uncached plugin will break the build until updated, complicating initial setup.

Decision Outcome

Gradle 8.14 (latest stable 8.x) is chosen over Gradle 9 for the initial setup.

The main reasons:

• Spring Boot 4.0 requires Gradle 8.14 as minimum; upgrading from 8.8 is necessary in any case.
• Gradle 9 is technically compatible with Spring Boot 4.0, but the mandatory Configuration Cache creates unacceptable risk until the openapi-generator-gradle-plugin Gradle 9 compatibility is confirmed (see issue #22084).
• ktlint-gradle 12.1.1 Gradle 9 support is unverified; a formatter breaking the build on day one is a poor start.

Upgrade trigger: revisit Gradle 9 once openapi-generator and ktlint-gradle confirm support. The upgrade itself will be low-risk at that point since the Spring Boot 4.0 step is already done.