Skill: chensoul/spring-boot-2-to-3 (version 1.0.1)

--- name: spring-boot-2-to-3 description: Migrate Spring Boot 2.7.x applications to Spring Boot 3.x with a recipe-first OpenRewrite workflow, then complete manual compatibility fixes and verification. Use only when the project is already on Boot 2.7.x; projects on 2.6 or earlier may fail—upgrade to 2.7.x first. Covers pom.xml/build.gradle, javax-to-jakarta, Spring Security config, dependency alignment, Dockerfile Java base image. --- # Spring Boot 2 to 3 Upgrade ## Overview Upgrade a **Spring Boot 2.7.x** service to 3.x in controlled stages: baseline capture, automated OpenRewrite migration, manual compatibility fixes, and regression validation. Prefer small, verifiable commits and keep each migration stage reversible. ## Supported source version - **This skill applies only to projects on Spring Boot 2.7.x.** The OpenRewrite recipe chain and manual checklist assume a 2.7.x baseline. - **If the project is on Spring Boot 2.6 or earlier**, do not run this skill directly—upgrades may fail or be incomplete. First upgrade the project to **2.7.x** (e.g. with `UpgradeSpringBoot_2_7` or manual POM changes), get the build and tests green, then use this skill to migrate 2.7.x → 3.x. - At the start of the workflow, **verify** the Boot version (e.g. from parent or `spring-boot.version`); if it is not 2.7.x, stop and tell the user to upgrade to 2.7.x first. ## Target version - **Spring Boot**: Prefer the **latest 3.5.x** line for new migrations. Versions 3.0–3.4 are transition lines; 3.5.x is the current stable target. When using OpenRewrite, use the `UpgradeSpringBoot_3_5` recipe (or the latest Boot 3.x recipe available). - **API docs (Springfox → springdoc)**: With **Spring Boot 3.5** use **springdoc-openapi 2.8.x**. Do not use springdoc-openapi 3.0.0 for Boot 3.5—3.0.0 targets Spring Boot 4. Check [springdoc releases](https://github.com/springdoc/springdoc-openapi/releases) for the exact 2.8.x version aligned to your Boot 3.5.x. ## What This Skill Does - ✅ Automated Spring Boot 2 → 3 upgrade (target latest 3.5.x) - ✅ JDK 8 → 21 migration - ✅ javax.* → jakarta.* namespace migration - ✅ Hibernate 5 → 6 adaptation - ✅ Configuration property updates - ✅ Dependency version resolution - ✅ **Dockerfile / container image**: upgrade Java base image to 17+ (or 21) via OpenRewrite [rewrite-docker](https://github.com/openrewrite/rewrite-docker) or text-based recipes - ✅ Full validation and testing workflow ## Prerequisites Check - **Spring Boot version**: The project must be on **2.7.x**. If it is 2.6 or earlier, do not proceed with this skill; instruct the user to upgrade to 2.7.x and pass tests first. - Before starting, verify (according to project build tool): ```bash java -version # Need JDK 17+ to run OpenRewrite mvn -version # Maven 3.8.1+ if using pom.xml ./gradlew --version # If using build.gradle / build.gradle.kts ``` If target workflow includes `UpgradeToJava21`, ensure JDK 21 toolchain is available in CI and runtime image. If missing, guide user to install or offer to create installation script. ## Workflow ### 1) Confirm Upgrade Path and Baseline 1. Detect build tool (`pom.xml` or `build.gradle`/`build.gradle.kts`), Java version, and test commands. **Confirm the project is on Spring Boot 2.7.x** (from parent or property); if not, stop and ask the user to upgrade to 2.7.x before using this skill. 2. **Verify the project compiles and tests pass** (e.g. `./mvnw -q compile test` or `./gradlew build`). Do not start migration until baseline is green; if there are known failures, document them and get user sign-off before proceeding. 3. Record current versions for Spring Boot, Spring Cloud, Spring Security, Hibernate, and API doc libs. 4. **Create safety checkpoints** only after baseline is green. **Run the following git command yourself** (do not ask the user to run it). The **current branch** (e.g. `main`) is already the rollback anchor—no need to create a separate backup branch. Create and switch to a **working branch** for the migration: `git checkout -b upgrade/sb3-<target-version>`. If rollback is needed, switch back to the original branch or compare against it. 5. Run the check script from this skill’s `scripts/` directory, passing the target project path: `scripts/check.sh <project-dir>` (e.g. from workspace root: `spring-boot-2-to-3/scripts/check.sh <project-dir>`). It captures Boot version hints, `javax` residue, and Springfox usage. 6. Save baseline artifacts (`dependency tree`, test summary, startup log) under the `docs/` directory. 7. If the project ships with a **Dockerfile** (or similar container build), record the current Java base image (e.g. `eclipse-temurin:11-jdk`) so it can be aligned to the target Java version (17 or 21) after the code migration. Use this phase to answer: - Is Java 17+ already active? - Does the project still use `javax.*` imports? - Does the project rely on removed/deprecated Boot 2 behavior? ### 2) Apply OpenRewrite First 1. Use OpenRewrite recipes to perform the broad mechanical migration from Boot 2 to Boot 3. 2. **Run** `git add` and `git commit` for the recipe-generated changes only (message prefix `chore(rewrite):`). Do not ask the user to commit. 3. Build and run tests to expose remaining manual issues. 4. If the target project has its own OpenRewrite/migration scripts, run those and retain stage logs. Load [references/openrewrite-recipes.md](references/openrewrite-recipes.md) for Maven/Gradle commands and recipe sets. ### 3) Perform Manual Compatibility Fixes 1. Resolve compile/runtime issues not fully covered by recipes. 2. Focus on namespace migration (`javax` -> `jakarta`), security config changes, and framework-specific behavior changes. 3. Align dependent libraries to Boot 3 compatible versions. 4. Keep fixes scoped and grouped by concern. 5. If identical issues appear across modules/repos, extract them into custom OpenRewrite recipes for reuse. 6. **Run** `git add` and `git commit` once per topic (e.g. `jakarta`, then `security`, `httpclient`, `tests`) to keep rollback granular. Execute the commits yourself; do not ask the user to run git. 7. **Dockerfile**: Upgrade the Java base image in `Dockerfile` (or container build) to match the target JDK (17+ or 21). Use OpenRewrite [rewrite-docker](https://docs.openrewrite.org/recipes/docker) (e.g. `Change Docker FROM`) or a text-based recipe; see [references/openrewrite-recipes.md](references/openrewrite-recipes.md) and [references/manual-fix-checklist.md](references/manual-fix-checklist.md). Load [references/manual-fix-checklist.md](references/manual-fix-checklist.md) and execute only relevant sections. ### 4) Validate End-to-End 1. Run unit/integration tests. 2. Start the app and check key health/business endpoints. 3. Review startup logs for warnings related to migration. 4. Run `scripts/check.sh` again (with the project path) and compare with baseline (e.g. no remaining `javax`). 5. Summarize remaining risk and follow-up tasks. 6. If runtime failures appear (`NoSuchMethodError`, `ApplicationContext` load issues), run targeted triage from `references/manual-fix-checklist.md`. 7. **Generate an upgrade report**: create a file under `docs/` (e.g. `docs/<yyyymmdd>-upgrade-summary.md`) containing: date, original branch (rollback anchor) and working branch, target Boot/Java versions, summary of changes by stage, validation result (compile/test), remaining risks or follow-up items. This gives the user and future readers a single place to see what was done and what to do next. ### 5) Rollback and Failure Handling (when something goes wrong) Apply as needed during or after stages 2–4; not a sequential step after validation. **On any failure (compile, test, or runtime): rollback and generate a failure report.** 1. **Rollback**: Restore a safe state so the repo is usable again. - If the failure is on the **working branch** (e.g. after OpenRewrite or a manual fix): either reset to the last good commit on that branch, or switch back to the **original branch** (e.g. `git checkout main`) so the user is on the pre-migration state. Prefer reverting topic commits or resetting the working branch before abandoning it; only switch to the original branch if recovery on the working branch is not practical. - The original branch must remain unchanged; use it as the rollback target when needed. 2. **Failure report**: Create a file under `docs/` (e.g. `docs/<yyyymmdd>-upgrade-failure.md`) containing: date, branch and commit at failure, **stage where it failed** (e.g. after OpenRewrite, after manual fix, during test), **error summary** (compile errors, test failures, or runtime exception), commands run, and **suggested next actions** (e.g. run recipes in smaller batches, fix a specific dependency, or upgrade to 2.7.x first). This gives the user a clear record of what went wrong and how to proceed. 3. If rewrite batch breaks compile: after rollback and failure report, the user may retry with recipes in smaller batches (see `references/openrewrite-recipes.md` for incremental recipe sequence). 4. If runtime regression is high-risk: after rollback and failure report, suggest comparing against the original branch and reverting topic commits on the working branch on a retry. ## Execution Rules - **Run all git commands yourself** (branch, commit) as part of the workflow; do not instruct the user to run git. The user should not need to execute any git commands for the migration. - Prefer "recipe-first" over ad-hoc hand edits. - Use `scripts/check.sh` before and after migration to compare baseline drift. - Keep migration commits small and thematic; **perform the commits yourself**: - Commit A: baseline and build setup (if any) - Commit B: OpenRewrite output - Commit C+: manual fixes by topic (including Dockerfile Java base image if present) - **Use the current branch as the rollback anchor**; create only a working branch (e.g. `upgrade/sb3-3.5`) for the migration. Do not create a separate backup branch—the original branch is the backup. - **On failure: always rollback to a safe state and generate a failure report** in `docs/` (e.g. `docs/<yyyymmdd>-upgrade-failure.md`) with stage, error summary, and next actions. Do not leave the repo in a broken state without a written report. - Never assume all changes are safe after a successful compile; run tests and boot smoke checks. - If tests are missing, create a minimal smoke checklist and report explicit risk. ## Output Contract When using this skill, return: 1. A concise migration plan for this repo. 2. Exact commands run (including git: branch, commit) and rewrite + verification commands. 3. Files changed grouped by migration stage. 4. Remaining blockers/risks with next actions. 5. Any **CI/CD or Dockerfile** changes (e.g. Java version in pipeline, base image) so they are not forgotten. 6. **On success**: path to the generated **upgrade report** (e.g. `docs/<yyyymmdd>-upgrade-summary.md`). **On failure**: path to the **failure report** (e.g. `docs/<yyyymmdd>-upgrade-failure.md`) and confirmation that rollback was performed.


Security scan verdicts — ClawScan: clean | static analysis:  | VirusTotal: clean | SkillSpector: clean (LOW)