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>
5.5 KiB
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 (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 14.2.0 Gradle 9 support needs verification.
- The
io.spring.dependency-managementplugin used to resolve the Spring BOM has known friction with Gradle 9 and would need to be replaced by a nativeplatform()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.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 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-managementplugin is replaced by cleaner nativeplatform()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.gradlefiles; impact on the spec-first code generation task specifically needs verification. - ktlint-gradle 14.2.0 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 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.