add ADRs for gradle and spring boot version and version smoke-tests

2026-06-09 15:20:21 +02:00
parent 019883c8e7
commit a030f7abb6
6 changed files with 382 additions and 0 deletions
@@ -0,0 +1,113 @@
+# 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](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 12.1.1](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.8/release-notes.html)
+
+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](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 12.1.1](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 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.