spring-boot-migration-guide

Reference and runnable demo for the two breaking-change migrations most Java/Spring teams are navigating in 2026: 2.7 → 3.x (javax → jakarta) and 3.5 → 4.x (Spring Framework 7, Jakarta EE 11, Jackson 3, modular starters).

Two things live here, deliberately kept together:

1. docs/ — the written guides. Organized by what actually breaks the build vs. what breaks silently at runtime, cross-checked against primary sources (the official spring-projects/spring-boot wiki, docs.spring.io) rather than just aggregated from blog posts — one widely-shared post claims Spring Boot 4 requires Java 21, which is false, and this reference corrects that inline.

2. app/ — a small Spring Boot REST service (JPA entity, repository, controller, security config) that actually is the migration, not just a description of it. The same codebase, evolved across three git tags:

   Tag	Spring Boot	What changed to get here
   2.7-baseline	2.7.18	Starting point: javax namespace, authorizeRequests()/antMatchers()
   3.5-bridge	3.5.16	jakarta namespace, authorizeHttpRequests()/requestMatchers()
   4.1-target	4.1.0	Modular starter (spring-boot-starter-webmvc, spring-boot-starter-webmvc-test)

   git diff 2.7-baseline..3.5-bridge -- app shows the real diff for the first hop; git diff 3.5-bridge..4.1-target -- app shows the second. That's the point — it's easier to trust a diff you can run yourself than a code block in a guide.

Verification status — read this before trusting the code

There is no CI in this repo. Verify locally before relying on any tag:

git checkout 2.7-baseline && cd app && mvn -q verify && cd ..
git checkout 3.5-bridge   && cd app && mvn -q verify && cd ..
git checkout 4.1-target   && cd app && mvn -q verify && cd ..

Known history worth knowing before you do: the 4.1-target tag originally shipped with the generic spring-boot-starter-test dependency, which does not provide MockMvc or Jackson once the app is on the modular spring-boot-starter-webmvc — it was replaced with spring-boot-starter-webmvc-test. That fix has not been confirmed by a clean, unambiguous passing build — run mvn verify yourself on this tag before treating it as working. If it still fails, check the exact compiler error first (missing symbol vs. dependency-resolution failure are different problems with different fixes) rather than adding more dependencies speculatively.

License

MIT — see LICENSE.