Customize the Java project upgrade plan when using GitHub Copilot app modernization

This article describes how to customize the Java project upgrade plan generated by GitHub Copilot app modernization.

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.

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.

Example plan.md file structure

The following sections describe a sample plan.md file structure in order to illustrate the customization points.

Key parameters

The following sections describe key parameters in the plan that you can modify.

Build tool command option

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 or Gradle CLI documentation, depending on your project.

Examples:

For Maven: Build tool command options: -Dmaven.javadoc.skip=true -s "/path/to/custom/settings.xml"
For Gradle: Build tool command options: --info -Penv=production

Note

Replace the path with your actual settings file location as needed. This path shown is just an example.

Test validation

Located under the Additional Tasks section, you can enable or disable test execution by modifying the run tests before and after the upgrade flag.

Set to true to enable unit tests before and after upgrade.
Set to false to skip test validation.

This setting controls whether the tool runs unit tests to verify functional correctness during the upgrade.

By adjusting these settings, you can fine-tune the upgrade process to better suit your project's requirements.

Customize upgrade goals and provide guidelines

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.

The Upgrade Goals section

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:

## Upgrade Goals
- Upgrade from Java 17 to 21
- Upgrade org.apache.logging.log4j:* to 2.24.3 
- Upgrade org.internal.lib to 2.0

The Guidelines section

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.

You can include any instructions that help steer how Copilot modifies code, such as the following instructions:

Guidance on which tools, recipes, or frameworks to use for code changes.
Constraints or prohibitions on certain upgrade approaches.
Code style or convention requirements.
Links to internal files, documentation, or scripts the agent can access.
Domain knowledge helpful for fixing errors or performing upgrades.
Requirements for how the agent should annotate or comment on code changes.
Cleanup instructions for temporary artifacts created during the upgrade process.

The content of this section can be plain text, hyperlinks, or references to local files as long as Copilot can access them.