# Gradle Version

**Status:**
- proposed: 2026-06-09
- accepted: 2026-06-09
- rejected: -
- superseded: -

**Decision [accepted]:** Gradle 8.14.5 — 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](https://docs.gradle.org/9.3.0/release-notes.html) (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](https://docs.gradle.org/current/userguide/compatibility.html) 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](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes)
  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](https://github.com/OpenAPITools/openapi-generator/issues/22084)
  has a known Gradle 9 issue in its generated build files, and
  [ktlint-gradle 14.2.0](https://github.com/JLLeitschuh/ktlint-gradle) Gradle 9 support
  needs verification.
- The [`io.spring.dependency-management` plugin](https://github.com/spring-gradle-plugins/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](https://docs.gradle.org/8.14.5/release-notes.html)

The currently configured series (wrapper at 8.14.5, upgraded from 8.8 as part of the Spring Boot 4.0 migration).

#### 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](https://github.com/OpenAPITools/openapi-generator/issues/22084)
  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](https://docs.gradle.org/9.3.0/release-notes.html)

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](https://github.com/OpenAPITools/openapi-generator/issues/22084)
  has a known Gradle 9 issue in generated `build.gradle` files; impact on the spec-first
  code generation task specifically needs verification.
- [ktlint-gradle 14.2.0](https://github.com/JLLeitschuh/ktlint-gradle) 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](https://github.com/OpenAPITools/openapi-generator/issues/22084)).
- ktlint-gradle 14.2.0 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.