AWS amazonq documentation change
Summary
Added documentation for optional dependency upgrade file configuration, including YAML structure and workflow integration. Updated transformation steps to include dependency file validation and renumbered subsequent steps.
Security assessment
The changes introduce dependency version management capabilities but do not explicitly address vulnerabilities, security patches, or security incidents. While dependency management can indirectly impact security, there is no direct evidence of security vulnerability mitigation in the diff. The note about stable network connections is operational guidance, not security-specific.
Diff
diff --git a/amazonq/latest/qdeveloper-ug/code-transformation.md b/amazonq/latest/qdeveloper-ug/code-transformation.md index a9e24294d..7e9657c01 100644 --- a//amazonq/latest/qdeveloper-ug/code-transformation.md +++ b//amazonq/latest/qdeveloper-ug/code-transformation.md @@ -5 +5 @@ -Supported Java upgrades and IDEsStep 1: PrerequisitesStep 2: Configure your projectStep 3: Transform your code +Supported Java upgrades and IDEsStep 1: PrerequisitesStep 2: Configure your projectStep 3: Create a dependency upgrade file (optional)Step 4: Transform your code @@ -21 +21,3 @@ To transform your code, Amazon Q first builds your code in the source language v - * Step 3: Transform your code + * Step 3: Create a dependency upgrade file (optional) + + * Step 4: Transform your code @@ -149 +151,70 @@ After installing Maven, add it to your `PATH` variable. For more information, se -## Step 3: Transform your code +## Step 3: Create a dependency upgrade file (optional) + +You can provide Amazon Q with a _dependency upgrade file_ , a YAML file that lists your project's dependencies and which versions to upgrade to during a transformation. By providing a dependency upgrade file, you can specify third and first party dependencies that Amazon Q might not otherwise know to upgrade. + +First party dependencies refer to the libraries, plugins, and frameworks that your organization maintains and are only available locally or on your organization’s private network. Amazon Q is able to access your first party dependencies when it performs builds in your local environment. For more information, see [Building code in your local environment](./how-CT-works.html#java-local-builds). Third party dependencies are publicly available or open source dependencies that aren’t unique to your organization. + +You can specify first party dependencies you want to upgrade in a YAML file, and Amazon Q upgrades them during the JDK upgrade (for example, Java 8 to 17). You can initiate a separate transformation (17 to 17 or 21 to 21) after the initial JDK upgrade to upgrade third-party dependencies. + +Once Amazon Q performs a minimum JDK upgrade, you can initiate a separate transformation to upgrade all third party dependencies. Alternatively, you can specify third party dependencies and their versions in a YAML file to only upgrade those dependencies during the library upgrade transformation. + +Amazon Q will prompt you to provide a dependency upgrade file during the transformation. If you want to provide one, first make sure you've configured the file properly. The following fields are required in the YAML file: + + * name - The name of the dependency upgrade file. + + * description (optional) - A description of the dependency upgrade file, and for which transformation. + + * dependencyManagement - Contains the list of dependencies and plugins to upgrade. + + * dependencies - Contains the name and version of the libraries to upgrade. + + * plugins - Contains the names and versions of the plugins to upgrade. + + * identifier - The name of the library, plugin, or other dependency. + + * targetVersion - The version of the dependency to upgrade to. + + * versionProperty (optional) - The version of the dependency you're defining, as set with the `properties` tag in your application's `pom.xml` file. + + * originType - Whether the dependency is first or third party, specified by either FIRST_PARTY or THIRD_PARTY. + + + + +Following is an example of a dependency upgrade YAML file, and the required configuration for Amazon Q to parse: + + + name: dependency-upgrade + + description: "Custom dependency version management for Java migration from JDK 8/11/17 to JDK 17/21" + + + dependencyManagement: + + dependencies: + + - identifier: "com.example:library1" + + targetVersion: "2.1.0" + + versionProperty: "library1.version" # Optional + + originType: "FIRST_PARTY" + + - identifier: "com.example:library2" + + targetVersion: "3.0.0" + + originType: "THIRD_PARTY" + + plugins: + + - identifier: "com.example.plugin" + + targetVersion: "1.2.0" + + versionProperty: "plugin.version" # Optional + + originType: "THIRD_PARTY" + +## Step 4: Transform your code @@ -158,0 +230,4 @@ If you navigate away from your IDE before the transformation starts, the transfo +###### Note + +Do not turn off or close your local machine during the code transformation because client-side build requires a stable network connection. + @@ -170 +245 @@ JetBrains - 4. Amazon Q begins the transformation. You can view progress on the **Transformation details** tab. + 4. Amazon Q prompts you to provide an upgrade dependency file. If you have configured a YAML with the dependencies and version to upgrade to, add your file. Amazon Q will validate the file to ensure it's configured correctly. If you get an error, review the format and required fields described in Step 3: Create a dependency upgrade file (optional). @@ -172 +247 @@ JetBrains - 5. After the transformation is complete, you can verify the upgraded code before updating your project. To view the new code, go to the **Transformation details** tab and then choose **View diff**. In the **Apply patch** window that appears, choose a file to open a diff view with your source code and upgraded code. + 5. Amazon Q begins the transformation. You can view progress on the **Transformation details** tab. @@ -174 +249 @@ JetBrains - 6. To accept the changes that Amazon Q made, choose **View diff** to open the **Apply patch** window. Select all the updated files, and choose **OK** to update your project in place. + 6. After the transformation is complete, you can verify the upgraded code before updating your project. To view the new code, go to the **Transformation details** tab and then choose **View diff**. In the **Apply patch** window that appears, choose a file to open a diff view with your source code and upgraded code. @@ -176 +251,3 @@ JetBrains - 7. To get details about how your code was upgraded and suggested next steps, on the **Transformation details** tab, choose **View transformation summary**. + 7. To accept the changes that Amazon Q made, choose **View diff** to open the **Apply patch** window. Select all the updated files, and choose **OK** to update your project in place. + + 8. To get details about how your code was upgraded and suggested next steps, on the **Transformation details** tab, choose **View transformation summary**. @@ -194 +271,3 @@ Visual Studio Code - 6. Amazon Q begins the transformation. You can view progress on the **Transformation Hub** tab. + 6. Amazon Q prompts you to provide an upgrade dependency file. If you have configured a YAML with the dependencies and version to upgrade to, add your file. Amazon Q will validate the file to ensure it's configured correctly. If you get an error, review the format and required fields described in Step 3: Create a dependency upgrade file (optional). + + 7. Amazon Q begins the transformation. You can view progress on the **Transformation Hub** tab. @@ -196 +275 @@ Visual Studio Code - 7. After the transformation is complete, the **Proposed Changes** tab opens. To verify the upgraded code before updating your project, choose **Download proposed changes**. Choose a file to open a diff view with your source code and upgraded code. + 8. After the transformation is complete, the **Proposed Changes** tab opens. To verify the upgraded code before updating your project, choose **Download proposed changes**. Choose a file to open a diff view with your source code and upgraded code. @@ -198 +277 @@ Visual Studio Code - 8. To accept the changes Amazon Q made, go to the **Proposed Changes** tab and choose **Accept**. + 9. To accept the changes Amazon Q made, go to the **Proposed Changes** tab and choose **Accept**. @@ -200 +279 @@ Visual Studio Code - 9. To get details about how your code was upgraded and suggested next steps, on the **Transformation Hub** , choose the **Views and More Actions** ellipsis button, and then choose **Show Transformation Summary**. + 10. To get details about how your code was upgraded and suggested next steps, on the **Transformation Hub** , choose the **Views and More Actions** ellipsis button, and then choose **Show Transformation Summary**.