Help upgrade a Java project step by step and adopt new language features safely.
Need a more powerful, automated upgrade?
The Microsoft plugin modernize-java ("GitHub Copilot modernization - Java Upgrade CLI Plugin", also listed in this repository's plugins/external.json) upgrades Java applications from the command line. It can:
- analyze the project, assess dependencies and generate a customizable upgrade plan you can review and edit;
- execute the plan to automatically transform the codebase;
- fix build issues and resolve migration errors during the upgrade, running test validations;
- validate the application against known CVEs after the upgrade;
- output a detailed summary (file changes, updated dependencies, test results, remaining issues) suitable for PRs or CI logs.
This skill provides lightweight, step-by-step guidance and works without the plugin; the plugin is the more powerful option for large or multi-step upgrades. It is a separate Microsoft plugin, not part of this repository's skills. To try it (see the plugin README for the recommended model):
npm install -g @github/copilot
copilot plugin marketplace add microsoft/modernize-java
copilot plugin install modernize-java@modernize-java
copilot --agent modernize-java:modernize-java
Workflow
- Detect the current and target versions. Read
pom.xml(maven.compiler.release,java.version, toolchains),build.gradle*(java.toolchain,sourceCompatibility) and CI files. Never assume a target: ask the user if it is not stated. - Upgrade one LTS at a time (11 → 17 → 21 → 25). Build and run the tests after each step.
- Load only the guide you need from the table below. Do not load all of them.
- Update the build first (compiler release, plugins, dependencies that need newer versions), then adopt language features incrementally in small, reviewable changes.
- Verify:
./mvnw verifyor./gradlew build, and fix deprecation and removal warnings before adopting new features. - Automate and check upstream. Use OpenRewrite when available (for example
org.openrewrite.java.migrate.UpgradeToJava21) and always fetch the version-specific official guide before editing; review the generated diff.
Upstream sources (read before upgrading)
Fetch the page for the target version; prefer it over this skill when they conflict. Full list with build-tool and agent compatibility pages: references/upstream-sources.md.
- OpenJDK release page: https://openjdk.org/projects/jdk/21/ (change the number) and JEP index https://openjdk.org/jeps/0
- Oracle migration guide: https://docs.oracle.com/en/java/javase/21/migrate/getting-started.html
- Oracle release notes: https://www.oracle.com/java/technologies/javase/21-relnote-issues.html
jdeprscan/jdeps: https://docs.oracle.com/en/java/javase/21/docs/specs/man/jdeprscan.html, https://docs.oracle.com/en/java/javase/21/docs/specs/man/jdeps.html- Gradle compatibility matrix: https://docs.gradle.org/current/userguide/compatibility.html
- OpenRewrite: https://docs.openrewrite.org/recipes/java/migrate/upgradetojava21
Per-version guides
| Upgrade | Guide |
|---|---|
| Java 11 → 17 | references/java-11-to-17.md |
| Java 17 → 21 | references/java-17-to-21.md |
| Java 21 → 25 | references/java-21-to-25.md |
Rules
- Prefer behavior-preserving refactorings; do not change public APIs unless asked.
- Detect the project's frameworks (Spring Boot, Quarkus, Jakarta EE) and check their minimum supported Java version before raising the target.
- Do not adopt preview features unless the user opts in and the build enables them explicitly.
- For
javax.*tojakarta.*namespace changes, use thejavax-to-jakarta-migrationskill if it is installed (gh skills install github/awesome-copilot javax-to-jakarta-migration); otherwise do the migration inline: update imports,META-INFservice files and XML descriptors, and bump dependencies to Jakarta EE 9+ equivalents. - If the
modernize-javaplugin is installed and the user wants an automated upgrade, defer to it and use this skill for the per-version guides and thejavaxtojakartasafeguards.