AWS amazonq documentation change
Summary
Added documentation for dependency upgrade file configuration, updated CLI tool version to 0.6.0, added transformation plan modification options, and renumbered steps
Security assessment
The changes primarily add functionality for dependency management and transformation customization. While the dependency upgrade file includes 'originType' classification (FIRST_PARTY/THIRD_PARTY), this appears to be organizational rather than security-focused. No vulnerabilities, access controls, or authentication changes are addressed beyond existing IAM Identity Center references.
Diff
diff --git a/amazonq/latest/qdeveloper-ug/run-CLI-transformations.md b/amazonq/latest/qdeveloper-ug/run-CLI-transformations.md index 23e02272f..6632f68a9 100644 --- a//amazonq/latest/qdeveloper-ug/run-CLI-transformations.md +++ b//amazonq/latest/qdeveloper-ug/run-CLI-transformations.md @@ -5 +5 @@ -PrerequisitesStep 1: Choose authentication method and add permissionsStep 2: Install the toolStep 3: Configure and authenticateStep 4: Run a transformation +PrerequisitesStep 1: Choose authentication method and add permissionsStep 2: Install the toolStep 3: Create a dependency upgrade file (optional)Step 4: Configure and authenticateStep 5: Run a transformation @@ -28 +28 @@ Before you begin a transformation on the command line, the following prerequisit - * If you are performing custom transformations, you have installed the ast-grep tool. To install and set up ast-grep, see [Installation](https://ast-grep.github.io/guide/quick-start.html#installation) in the ast-grep documentation. + * If you have specific dependencies you want Amazon Q to upgrade, you have configured a dependency upgrade file. @@ -66 +66 @@ You can specify this configuration on your command line by running `aws configur -You provide the AWS CLI profile you configured in Step 3: Configure and authenticate. +You provide the AWS CLI profile you configured in Step 4: Configure and authenticate. @@ -70 +70 @@ You provide the AWS CLI profile you configured in Step 3: Configure and authenti -To authenticate with IAM Identity Center, you must be [subscribed to Amazon Q Developer Pro](./q-pro-tier.html) and provide the Start URL to authenticate through your subscription. You or your administrator can find the Start URL in the Amazon Q Developer console. For more information see, [Managing account details in Amazon Q Developer](./manage-account-details.html). +To authenticate with IAM Identity Center, you must be [subscribed to Amazon Q Developer Pro as a workforce user](./subscribe-users.html) by your administrator, and you must provide the Start URL to authenticate through your subscription. You or your administrator can find the Start URL in the Amazon Q Developer console. For more information see, [Finding the Start URL for use with Amazon Q Developer](./manage-account-details.html). @@ -74 +74 @@ To add required permissions, see Add permissions. -You provide the Start URL in Step 3: Configure and authenticate. +You provide the Start URL in Step 4: Configure and authenticate. @@ -78 +78 @@ You provide the Start URL in Step 3: Configure and authenticate. - 1. [Download the Amazon Q command line tool for transformations](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.5.2.zip). + 1. [Download the Amazon Q command line tool for transformations](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.6.0.zip). @@ -92 +92 @@ To download a previous version of the command line tool, see [Version history](. - pip install amzn_qct_cli-0.5.2-py3-none-any.whl + pip install amzn_qct_cli-0.6.0-py3-none-any.whl @@ -96 +96 @@ To download a previous version of the command line tool, see [Version history](. -If you are using an older version of the command line tool for transformations, replace `0.5.2` with the [version](./transform-CLI-versions.html) you downloaded. +If you are using an older version of the command line tool for transformations, replace `0.6.0` with the [version](./transform-CLI-versions.html) you downloaded. @@ -105 +105,68 @@ If you are using an older version of the command line tool for transformations, -## Step 3: Configure and authenticate +## 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](./transform-CLI.html#local-builds). Third party dependencies are publicly available or open source dependencies that aren’t unique to your organization. + +For Amazon Q to upgrade any first party dependencies, you must specify them in the file. It can update third party dependencies that you don’t specify, but if there are any dependencies or versions you want to make sure it upgrades, add them to the file. + +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: Configure and authenticate @@ -145 +212 @@ For more information on how Amazon Q splits up the code changes, see [Reviewing -## Step 4: Run a transformation +## Step 5: Run a transformation @@ -149,2 +215,0 @@ Choose the type of transformation you're performing to see the required configur -For information on running custom transformations, see [Customizing transformations](./customize-CLI-transformations.html). - @@ -153,0 +219,37 @@ Java upgrade +**Modifying the transformation plan** + +During Java version upgrades, Amazon Q generates a transformation plan that you can review before the transformation begins. You have the option to request the following changes to the plan: + + * Which libraries Amazon Q upgrades, from the list included in the plan + + * Example prompts: + + * Only upgrade <dependency1>, <dependency2>, and <dependency5> + + * Don't upgrade <dependency1> or <dependency2> + + * The target version to upgrade a library to + + * Example prompts: + + * Upgrade <dependency> to this version instead <version> + + * Which steps Amazon Q should perform + + * Example prompts: + + * Only complete steps 1-7 + + * Don't run steps 5-9 + + * Add additional dependencies to upgrade (only an option when upgrading to a newer JDK version) + + * Example prompts: + + * Also upgrade <dependency1> to <version2> + + + + +###### Upgrade Java code + @@ -159 +261,9 @@ Java upgrade - 2. Amazon Q begins the transformation. It will output status updates throughout the transformation. When it’s complete, Amazon Q provides the path where the transformation results, logs, and configuration files are outputted. +Additional command options: + + * If you are specifying dependencies to upgrade, add the `--dependency_upgrade_file` option with the path to your dependency upgrade file. + + * If you don’t want to review or update the transformation plan, add the `--no-interactive` flag to your command. Amazon Q won’t ask you for feedback on the plan, and you won’t have the opportunity to request changes. + + 2. If you didn’t add the `--no-interactive` flag, Amazon Q will prompt you to provide feedback on the transformation plan. You can explain the changes you want to make in English natural language, and Amazon Q will update the plan if it can support the changes you request. + + 3. Amazon Q begins the transformation. It will output status updates throughout the transformation. When it’s complete, Amazon Q provides the path where the transformation results, logs, and configuration files are outputted. @@ -199 +309 @@ Transforming code on the command line -Customizing transformations +Troubleshooting