mhoennigandClaude Opus 5
35f06ec1ec
`gitTally` is the name of another product in the git space, so the rename is a precaution; nothing about what the build system does changes. The name follows one rule: `Werkator` where it is prose, capitalized where it is a Kotlin type and its file, lowercase everywhere a machine reads it — the command, packages, paths, configuration keys and values, the Gitea check context. Environment variables keep their convention and are uppercase throughout. Every configuration file is still found under its pre-rename name (`ConfigFiles`): `.gittally.yml` at the repository root, in a build worktree and as committed on a branch, `.git/gittally/.gittally.yml` for the machine layer. The current name wins where both exist, and the old file is then ignored rather than merged — two files side by side are a half-done rename, not a layering. Without the fallback an installation that updated without renaming would not fail: a configuration that is not found leaves every setting at its default, so it would come up looking healthy while having forgotten its credentials and its builds. `docs/werkator-migrationsplan.md` lists what the fallback does not cover and has to be moved by hand — above all the state directory `.git/werkator/`, which holds the build history, the control token and the worktrees, and has no fallback of its own. `docs/migration-from-legacy.md` is deleted with this: it mapped the legacy script's environment variables, and every host it addressed has long since moved to the YAML configuration. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
114 lines
5.5 KiB
Markdown
114 lines
5.5 KiB
Markdown
# 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
|
|
|
|
Werkator 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.
|