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

Spring Boot Version

Status:

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

Decision [accepted]: Spring Boot 4.0.6 — only actively-supported version; springmockk 5.0.1 provides @MockkBean for Spring Boot 4.0.

Context and Problem Statement

werkator 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	Version	Role	Spring Boot 4.0 status
picocli-spring-boot-starter	4.7.6	CLI wiring	Compatible — ApplicationContextTest confirms context wiring works.
springmockk	5.0.1	@MockkBean in tests	Compatible — 5.x released specifically for Spring Boot 4.0; @MockkBean verified.
kotest-extensions-spring	6.1.5	Kotest + @SpringBootTest	Compatible — 6.x (new groupId io.kotest) required; config moved to io.kotest.provided.ProjectConfig.
wiremock-spring-boot	4.2.1	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 5.x is required. Version 4.x is Spring Boot 3.x only. Version 5.0.1 adds Spring Boot 4.0 support; @MockkBean / @SpykBean work as expected. As an alternative, register MockK mocks via @TestConfiguration without the springmockk dependency:

  @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) }
      }
  }
  

• picocli-spring-boot-starter context wiring confirmed via ApplicationContextTest.
• kotest-extensions-spring 6.x (groupId io.kotest) is required for Spring Boot 4.0. The project config must be placed at io.kotest.provided.ProjectConfig (Kotest 6 discovery requirement).
• 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.

All ecosystem blockers are resolved. The codebase runs Spring Boot 4.0.6.