|
| 1 | +--- |
| 2 | +title: Customize the Java Project Upgrade Plan When Using GitHub Copilot App Modernization |
| 3 | +description: Describes how to customize the upgrade plan generated by GitHub Copilot app modernization. |
| 4 | +author: KarlErickson |
| 5 | +ms.author: karler |
| 6 | +ms.reviewer: xinrzhu |
| 7 | +ms.topic: how-to |
| 8 | +ms.date: 11/18/2025 |
| 9 | +ms.custom: devx-track-java |
| 10 | +--- |
| 11 | + |
| 12 | +# Customize the Java project upgrade plan when using GitHub Copilot app modernization |
| 13 | + |
| 14 | +This article describes how to customize the Java project upgrade plan generated by GitHub Copilot app modernization. |
| 15 | + |
| 16 | +When you initiate an upgrade session, GitHub Copilot generates a **plan.md** file that outlines the steps and tasks required for the upgrade. This file serves as a blueprint for the upgrade process, which you can customize to better fit your project's needs. |
| 17 | + |
| 18 | +After the tool generates the **plan.md** file, it automatically opens in the Visual Studio Code editor. At this stage, you can review and customize the plan to ensure it aligns with your specific upgrade goals. |
| 19 | + |
| 20 | +## Example plan.md file structure |
| 21 | + |
| 22 | +The following sections describe a sample **plan.md** file structure in order to illustrate the customization points. |
| 23 | + |
| 24 | +## Key parameters |
| 25 | + |
| 26 | +The following sections describe key parameters in the plan that you can modify. |
| 27 | + |
| 28 | +### Build tool command option |
| 29 | + |
| 30 | +This option is located under **Project Information**, and enables you to define custom command-line parameters for build tool execution. For valid options, see the [Maven CLI](https://maven.apache.org/ref/current/maven-embedder/cli.html) or [Gradle CLI](https://docs.gradle.org/current/userguide/command_line_interface.html) documentation, depending on your project. |
| 31 | + |
| 32 | +Examples: |
| 33 | + |
| 34 | +- **For Maven**: `Build tool command options: -Dmaven.javadoc.skip=true -s "/path/to/custom/settings.xml"` |
| 35 | + |
| 36 | +- **For Gradle**: `Build tool command options: --info -Penv=production` |
| 37 | + |
| 38 | +> [!NOTE] |
| 39 | +> Replace the path with your actual `settings` file location as needed. This path shown is just an example. |
| 40 | +
|
| 41 | +:::image type="content" source="media/customize-upgrade-plan/upgrade-plan.png" alt-text="Screenshot of Visual Studio Code that shows an example upgrade plan with upgrade targets highlighted." lightbox="media/customize-upgrade-plan/upgrade-plan.png"::: |
| 42 | + |
| 43 | +### Test validation |
| 44 | + |
| 45 | +Located under the **Additional Tasks** section, you can enable or disable test execution by modifying the `run tests before and after the upgrade` flag. |
| 46 | + |
| 47 | +- Set to `true` to enable unit tests before and after upgrade. |
| 48 | +- Set to `false` to skip test validation. |
| 49 | + |
| 50 | +This setting controls whether the tool runs unit tests to verify functional correctness during the upgrade. |
| 51 | + |
| 52 | +By adjusting these settings, you can fine-tune the upgrade process to better suit your project's requirements. |
| 53 | + |
| 54 | +## Customize upgrade goals and provide guidelines |
| 55 | + |
| 56 | +In Java upgrade scenarios, you often need customization beyond standard JDK or framework upgrades - for example, to apply project-specific code changes or to update internal libraries the tool doesn't automatically detect. To support these needs, GitHub Copilot app modernization now enables customization within the upgrade plan. This capability enables you to provide your own recipes, instructions, and inputs to guide the upgrade process. You can perform this customization by modifying the **Upgrade Goals** and **Guidelines** sections. |
| 57 | + |
| 58 | +### The Upgrade Goals section |
| 59 | + |
| 60 | +In the **Upgrade Goals** section, you can now specify more upgrade targets along with the objectives in your initial prompt. For example, if the primary task is to upgrade the project from Java 17 to Java 21, but the project also requires upgrading Log4j from 1.x to 2.x, you can list that as an additional goal, as shown in the following example prompt: |
| 61 | + |
| 62 | +```prompt |
| 63 | +## Upgrade Goals |
| 64 | +- Upgrade from Java 17 to 21 |
| 65 | +- Upgrade org.apache.logging.log4j:* to 2.24.3 |
| 66 | +- Upgrade org.internal.lib to 2.0 |
| 67 | +``` |
| 68 | + |
| 69 | +### The Guidelines section |
| 70 | + |
| 71 | +The **Guidelines** section defines how Copilot should perform the upgrade. While the **Upgrade Goals** section focuses on what needs to be upgraded, the **Guidelines** section captures the methodology, conventions, tooling, and rules that guide Copilot's behavior during code transformation. |
| 72 | + |
| 73 | +You can include any instructions that help steer how Copilot modifies code, such as the following instructions: |
| 74 | + |
| 75 | +- Guidance on which tools, recipes, or frameworks to use for code changes. |
| 76 | +- Constraints or prohibitions on certain upgrade approaches. |
| 77 | +- Code style or convention requirements. |
| 78 | +- Links to internal files, documentation, or scripts the agent can access. |
| 79 | +- Domain knowledge helpful for fixing errors or performing upgrades. |
| 80 | +- Requirements for how the agent should annotate or comment on code changes. |
| 81 | +- Cleanup instructions for temporary artifacts created during the upgrade process. |
| 82 | + |
| 83 | +The content of this section can be plain text, hyperlinks, or references to local files as long as Copilot can access them. |
| 84 | + |
| 85 | +Examples: |
| 86 | + |
| 87 | +```prompt |
| 88 | +## Guidelines |
| 89 | +- Do not use Log4j 1 to Log4J 2 API bridge to upgrade to Log4J 2. |
| 90 | +- Please follow the code conventions defined in /xxx/bbb/rules.txt. |
| 91 | +- Please provide detailed comments explaining why each code change is necessary. |
| 92 | +- "com.example:internal-lib:2.0.0" is compatible with Java 21. |
| 93 | +- Use our internal MCP tool get_internal_lib_knowledge to retrieve compatibility information for internal libraries. |
| 94 | +- After the upgrade, please remove any temporary files created during the process, such as code modification scripts. |
| 95 | +
|
| 96 | +``` |
| 97 | + |
| 98 | +:::image type="content" source="media/customize-upgrade-plan/guidelines.png" alt-text="Screenshot of Java upgrade plan that contains the Upgrade Goals and Guidelines sections." lightbox="media/customize-upgrade-plan/guidelines.png"::: |
| 99 | + |
| 100 | +## See also |
| 101 | + |
| 102 | +[GitHub Copilot app modernization](/azure/developer/java/migration/migrate-github-copilot-app-modernization-for-java?toc=/java/upgrade/toc.json&bc=/java/upgrade/breadcrumb/toc.json) |
0 commit comments