# Upgrade Breaking Change Navigator > Plan and execute risky Spring Boot, Spring Framework, Kotlin, Gradle, JDK, and major dependency upgrades with explicit compatibility checkpoints and rollback thinking. Use when preparing or diagnosing a major version jump, navigating `javax` to `jakarta`, K2 adoption, plugin compatibility, auto-configuration drift, behavior changes in Hibernate or Security, or project-specific upgrade sequencing. - Skill: `jetbrains/upgrade-breaking-change-navigator` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add jetbrains/upgrade-breaking-change-navigator` - Raw SKILL.md: https://api.skillmd.com/api/skills/jetbrains/upgrade-breaking-change-navigator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: jetbrains (https://skillmd.com/u/jetbrains) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jetbrains/upgrade-breaking-change-navigator --- # Upgrade Breaking Change Navigator Source mapping: Tier 3 specialized skill derived from `Kotlin_Spring_Developer_Pipeline.md` (`SK-22`). ## Mission Turn a risky platform upgrade into a controlled sequence of small, verifiable moves. Optimize for incremental confidence, not for a single giant leap that hides the source of breakage. ## Read First - Current Gradle wrapper, Kotlin plugin, Spring Boot plugin, JDK, and key dependency versions. - Version catalogs, convention plugins, and BOM ownership. - Build failures, test failures, runtime startup failures, and deprecation reports. - The actual libraries and features in use: Security, Data JPA, WebFlux, AOT/native, messaging, serialization, cloud config. - Official upgrade notes when available. ## Upgrade Strategy 1. Identify the target version and the last known good current version. 2. Identify mandatory intermediate steps. Do not skip major lines casually. 3. Separate upgrade layers: - JDK - Gradle wrapper - Kotlin plugin and compiler - Spring Boot and Spring Framework - ecosystem libraries 4. Upgrade one authority at a time whenever possible. 5. After each step, verify: - dependency resolution - compile - tests - startup smoke 6. Record breakages by layer so the root cause stays attributable. ## Advanced Upgrade Hotspots - `javax.*` to `jakarta.*` is both source migration and dependency compatibility migration. - Spring Security DSL and filter-chain defaults change across major lines. "Compiles" does not mean "same auth behavior." - Hibernate upgrades can change SQL generation, lazy-loading behavior, sequence handling, and schema expectations. - Kotlin compiler upgrades can affect KAPT, KSP, compiler plugins, nullability inference, and generated bytecode shape. - Boot upgrades can change auto-configuration defaults, logging behavior, observability integration, and actuator exposure. - Native image or AOT support raises a different class of breakages around reflection, proxies, and configuration hints. - Testcontainers, MockK, bytecode instrumentation, and coverage tooling often lag core platform upgrades. - JSpecify or other nullability enhancements in upstream libraries may force new Kotlin compile warnings or source changes. ## Runtime And Tooling Nuances - JDK upgrades can tighten module encapsulation, change TLS defaults, alter DNS or timezone behavior, and surface illegal reflective access only in production-like environments. - Path-matching, error rendering, and Problem Details defaults can shift behavior at the web boundary even when controller code remains unchanged. - Observability migrations can change metric names, trace propagation, or log correlation behavior, breaking dashboards before the app "breaks." - Security upgrades frequently change defaults toward stricter behavior. A newly failing request may indicate a safer default, not a broken framework. - Gradle upgrades can invalidate custom build logic, remote cache assumptions, and plugin internals long before the application code notices. - Native-image or AOT-capable builds often need separate verification gates because JVM startup passing does not imply native correctness. ## Expert Heuristics - Upgrade the path that gives the highest diagnostic signal first, not merely the path that feels most foundational. - Upgrade the toolchain that constrains others first only when compatibility docs support that order; otherwise preserve the currently supported matrix as long as possible. - Let the platform BOM regain control of library families before trying to patch every individual dependency. - Treat deprecation warnings as migration guidance, not cosmetic noise, when they are in code paths touched by the upgrade. - If dashboards, alerts, or client contracts are version-sensitive, treat them as part of the upgrade scope, not post-upgrade cleanup. - If a library is not upgrade-ready, decide whether to pin temporarily, replace it, or postpone the platform target. Do not pretend all paths are equal. - Maintain a migration log per step: version change, observed failures, compensating fixes, and remaining known risks. This prevents rediscovery loops. - Prefer canary or staged deployment for behavior-changing upgrades even when compile and test phases are green. - Preserve a rollback path for deployable upgrades. A technically correct upgrade without operational reversibility is incomplete. ## Output Contract Return these sections: - `Current state`: the versions and high-risk features in use. - `Upgrade path`: the ordered sequence of upgrades. - `Breaking-change hotspots`: which parts of the codebase are most likely to fail and why. - `Verification gates`: what must pass after each step. - `Temporary mitigations`: acceptable short-lived pins or compatibility shims. - `Rollback note`: how to retreat safely if a step fails in a deployed environment. ## Guardrails - Do not skip major versions without a strong, project-specific reason. - Do not mix many unrelated upgrade axes into one untraceable patch if avoidable. - Do not assume compile success equals runtime safety. - Do not remove compatibility shims without proving callers no longer need them. ## Quality Bar A good run of this skill gives the team an upgrade path with clear checkpoints and known failure hotspots. A bad run is a giant version-bump patch followed by generic advice to "fix whatever breaks."