Java Framework Upgrade Pre-Flight Checklist
A pre-flight gate for Java JDK and framework upgrades. It covers dependency compatibility, the javax-to-jakarta namespace move, baseline testing, security scanning, and safe staged rollout.
When to Use This Checklist
Use this checklist before upgrading a Java application's JDK or framework, for example Java 8 to 17 or Spring Boot 2 to 3. These upgrades change language features, the module system, and, in Spring Boot 3, the base namespace from javax to jakarta. A pre-flight pass surfaces breaking changes before they reach a running environment.
How to Use This Checklist
Start with discovery: record current versions and audit every dependency for target-JDK compatibility. The largest single task in Spring Boot 3 is the javax-to-jakarta namespace move, so plan for it explicitly. Establish a green baseline test run before changing anything, then upgrade incrementally and re-run the suite at each step. Treat the vulnerability scan and a canary or blue-green rollout as gates.
Performance and image-build items are optional but valuable when latency or cold-start matters.
What Good Looks Like
A clean upgrade has every dependency confirmed compatible, all javax imports migrated, and the full test suite green on the new runtime. JVM flags are re-tuned, dependency scans show no new critical findings, and the change ships through a canary or blue-green deployment with a documented rollback to the previous JDK and artifact.
Common Pitfalls
Teams underestimate the jakarta namespace migration and the breakage in reflection-based libraries under the stricter module system. Removed JDK internal APIs surface only at runtime if not scanned for. Upgrading without a baseline test run hides whether failures are new. Skipping a canary turns every regression into a full outage.
Related Resources
See the test pyramid for layering your safety net, static application security testing in CI for the dependency scan, and blue-green and canary release practices for safe rollout. Semantic versioning helps you reason about dependency compatibility.