# 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](https://endoflife.date/spring-boot)
([HeroDevs April 2026 overview](https://www.herodevs.com/blog-posts/spring-boot-versions-eol-dates-and-latest-releases-april-2026))
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](https://github.com/spring-projects/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](https://picocli.info/) | 4.7.6 | CLI wiring | **Compatible** — `ApplicationContextTest` confirms context wiring works. |
| [springmockk](https://github.com/Ninja-Squad/springmockk) | 5.0.1 | `@MockkBean` in tests | **Compatible** — 5.x released specifically for Spring Boot 4.0; `@MockkBean` verified. |
| [kotest-extensions-spring](https://github.com/kotest/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](https://wiremock.org/docs/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](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes)

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:
  ```kotlin
  @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.