Skip to content
Browse the docs

Accepted5 Nov 2026

0021. Java build conventions: one convention plugin, warnings as errors, JUnit 6

View on GitHubReport a problem with this page

Context and Problem Statement#

ADR-0006 chooses Gradle and puts settings shared by every module in convention plugins. It names the quality gates but not how strict they are, how the build finds Java 25, or which JUnit. ADR-0006 says JUnit 5, but Spring Boot 4 has moved to JUnit 6 (ADR-0007).

What exactly does every Java module get from the build?

Decision Drivers#

  • The project is meant to be reference code: its build should be one a Java engineer holds up as an example.
  • Mistakes should fail the build, not appear as warnings nobody reads.
  • The build must work on any machine with any JAVA_HOME, and the same in CI.

Considered Options#

  • JUnit 6 (the Jupiter API) or JUnit 5.14
  • Warnings fail the build, or warnings are reported
  • NullAway on every io.archsim package, or only on packages marked @NullMarked

Decision Outcome#

Chosen options: "JUnit 6", "warnings fail the build", and "NullAway on every io.archsim package". Every module applies one convention plugin, build-logic/src/main/kotlin/archsim.java-conventions.gradle.kts, and configures nothing it sets:

  • Java 25. A Java 25 toolchain compiles with --release 25. gradle/gradle-daemon-jvm.properties makes Gradle itself run on JDK 25, downloading one if none is installed, so the build works whatever JAVA_HOME points to.
  • Static analysis. Error Prone with NullAway in JSpecify mode covers all of io.archsim. With -Xlint:all -Werror, every javac or Error Prone warning fails the build.
  • Tests. JUnit 6 and AssertJ. JUnit 6 is JUnit 5's Jupiter API, and the version Spring Boot 4 manages, so the tests won't need to change when stage 2 adds Spring. JaCoCo writes coverage reports after the tests.
  • Further test suites, such as the black-box apiTest (ADR-0019), are Gradle JVM test suites. check compiles and analyses them; they run only on request.
  • Build speed. The configuration cache, the build cache and parallel builds are on (gradle.properties).

Consequences#

  • Good, because one command, ./gradlew build, gives every module the same checks locally and in CI.
  • Good, because null-safety and Error Prone's bug patterns are enforced, not advisory.
  • Bad, because strictness has a cost: a contributor must follow Error Prone's suggestions. A finding is never suppressed; where a rule seems wrong, the owner decides (AGENTS.md, ADR-0030). NullAway's generic checks sometimes need a plain loop where a stream would do.
  • Bad, because a few third-party JUnit extensions may support JUnit 6 later than JUnit 5.

Confirmation#

./gradlew build fails on a formatting change, a nullness error or any compiler warning. The CI job java runs it.

More Information#