werkator/docs/adrs/0003-2026-06-09.spring-boot-version.md

Spring Boot Version

Status:

• proposed: 2026-06-09
• accepted: -
• rejected: -
• superseded: -

Decision [proposed]: Spring Boot 4.0 — only actively-supported version; springmockk workaround via @TestConfiguration until a compatible release is published.

Context and Problem Statement

GitTally is a greenfield Kotlin/Spring Boot project. A Spring Boot version must be chosen for the initial setup.

The choice is constrained by the support lifecycle: as of June 2026, almost the entire Spring Boot 3.x release train is already end-of-life.

Technical Background

Spring Boot support lifecycle (HeroDevs April 2026 overview) as of June 2026:

Version	EOL date	Status
3.5.x	June 30, 2026	Expires this month
4.0.x	December 2026	Active (current: 4.0.6)

Spring Boot 3.5.x is the final 3.x release; there will be no 3.6. The Spring project ended the 3.x train at 3.5 and continues in the 4.x line (Spring Boot milestones). Spring Boot 4.0 moves to Spring Framework 7 and Jakarta EE 11.

The key ecosystem dependencies and their Spring Boot 4.0 compatibility status:

Dependency	Role	Spring Boot 4.0 status
picocli-spring-boot-starter	CLI wiring	Untested; last documented target is Spring Boot 3.1. The integration is minimal (one IFactory bean), so it likely works in practice.
springmockk	@MockkBean in tests	Incompatible — confirmed Spring Boot 3.x only.
kotest-extensions-spring	Kotest + @SpringBootTest	Compatibility unconfirmed.
wiremock-spring-boot	HTTP stubbing in tests	Compatible — Spring Boot 4.0 explicitly supported since January 2026.

Considered Options

• Spring Boot 3.5.x (latest 3.x)
• Spring Boot 4.0.x

Spring Boot 3.5.x

The last actively-supported 3.x release.

Advantages

• Full compatibility with all current dependencies (picocli-spring-boot-starter, springmockk, kotest-extensions-spring).
• Well-known ecosystem; documentation and community resources are mature.

Disadvantages

• EOL June 30, 2026 — expires this month. Starting a project on a version ending within days is indefensible.
• Upgrading to Spring Boot 4.0 immediately after project start incurs migration cost at the worst possible time (early, before the codebase is stable).

Spring Boot 4.0

The current and only actively-supported major release.

Advantages

• The only version receiving security patches and updates beyond June 2026.
• Spring Framework 7 and Jakarta EE 11: active, long-term foundation.
• Aligns with Gradle 9 when that upgrade is eventually made (ADR 0002).
• Wiremock Spring Boot integration fully supports it.

Disadvantages

• springmockk is incompatible. The @MockkBean / @SpykBean annotations are not available. This matters in particular for @WebMvcTest (controller error-behaviour) and @DataJpaTest-adjacent tests where collaborators need to be mocked in the Spring context. The workaround is to register MockK mocks as Spring beans via @TestConfiguration, which preserves full MockK syntax (every { }, verify { }) at the cost of one inner configuration class per test file and an explicit clearMocks() call in beforeEach:

  @WebMvcTest(SomeController::class)
  @Import(SomeControllerTest.Mocks::class)
  class SomeControllerTest : FunSpec() {
      @TestConfiguration
      class Mocks {
          @Bean fun someService(): SomeService = mockk()
      }
      @Autowired lateinit var someService: SomeService
      init {
          beforeEach { clearMocks(someService) }
          // full MockK syntax available
      }
  }
  

  This is more verbose than @MockkBean but avoids mixing Mockito and MockK. Revisit once springmockk publishes a Spring Boot 4.0-compatible release.
• picocli-spring-boot-starter is untested against Spring Boot 4.0. The risk is low (the auto-configuration is a single IFactory bean with no framework-version-specific API), but it cannot be assumed safe until verified by a running context test.
• kotest-extensions-spring compatibility needs verification before the first @SpringBootTest test is written.
• Relatively new GA; fewer community examples for the 4.0 generation.

Decision Outcome

Spring Boot 4.0 is chosen.

The main reasons:

• Spring Boot 3.5.x expires this month; starting on it is not a viable option.
• Spring Boot 4.0 is the only release with active support through the foreseeable project lifetime.
• The ecosystem blockers are manageable:
  • picocli-spring-boot-starter risk is low and will be confirmed by the existing context-wiring smoke test (ApplicationContextTest).
  • springmockk is a test-only dependency; the short-term workaround (@TestConfiguration with mockk() beans, clearMocks() in beforeEach) preserves full MockK syntax in @WebMvcTest and @DataJpaTest tests without falling back to Mockito.
  • kotest-extensions-spring compatibility must be verified before the first @SpringBootTest test is written.

Open items before the code is upgraded:

1. Bump Spring Boot to 4.0.6 and verify ApplicationContextTest still passes.
2. Confirm picocli-spring-boot-starter works under the new context.
3. Confirm kotest-extensions-spring works with Spring Boot 4.0.
4. Replace @MockkBean usages with the @TestConfiguration + mockk() pattern until springmockk publishes a compatible release.