Writing OpenRewrite Migrations for Track 2 Libraries

Writing OpenRewrite Migrations for Track 2 Libraries

The goal of this wiki is to provide relevant information to assist in writing OpenRewrite migrations for Track 2 libraries. It is not a comprehensive guide of all capabilities provided by OpenRewrite. If you are unfamiliar with OpenRewrite, please review the official OpenRewrite documentation from Moderne.

Writing Library Migration Recipes

Recipe Structure

Best Practices

Testing Library Migration Recipes

Adding Additional Test Samples

Due to the IDEs ability to view the diff of an AssertionError, it is highly suggested that you use Intellij when testing recipes. The testGoldenImage test within the FullSampleMigrationTest test class is the test that runs the migration tests on all samples. The test is configured using the uber-recipe, meaning that the testGoldenImage test will run all recipes on all samples. The testing suite is configured to run recipes on all samples, presuming that they follow a specified directory structure. When adding additional samples to be tested, the test class FullSampleMigrationTest does not need to be altered.

When adding samples, be sure to verify that the samples compile to ensure that the migration accurately reflect what's available within public api for your library.

Required Testing Structure

For the FullSampleMigrationTest to work correctly, the samples must adhere to a specific directory structure:

• A library's samples directory must be as follows: <path_to_root>/sdk/tools/azure-openrewrite/src/test/resources/migrationExamples/<library-directory>
• Samples run individually as parameterized test cases. Each sample must have it's own encapsulating directory. Ex:
  • /migrationExamples/azure-core/sample1
  • /migrationExamples/azure-core/sample2
• Within each sample there must exist two directories with the names v1 and v2, where v1 contains all pre-migration sample java files (using the Track 2 library) and v2 contains all post-migration sample files (using Track 3 library). Ex:
  • /migrationExamples/azure-core/sample1/v1 : All unmigrated Track 2 java files that collectively represent sample 1.
  • /migrationExamples/azure-core/sample1/v2 : All migrated Track 3 java files that collectively represent sample 1.
• For every file within the v1 directory of a sample, there must be a file in the v2 directory for that sample with a matching filename.

Compiling Test Samples

To ensure that our samples are an accurate representation of both our Track 2 and Track 3 libraries, we make use of the azure-openrewrite-compiler-plugin, an internal tool that compiles both the pre- and post-migration samples using the Track 2 and Track 3 libraries respectively. To keep track of these dependency versions, we make use of maven profiles: Profile v1 to represent the Track 2 libraries dependencies and profile v2 to represent the Track 3 libraries dependencies. When adding samples for a new library, be sure to update the azure-openrewrite pom.xml file's v1 and v2 profiles with the appropriate dependencies for each.

Running the Compiler

Running the sample compiler requires two steps:

1. You compile the plugin using the command: ../sdk/tools> mvn clean install -f ./azure-openrewrite-compiler-maven-plugin/pom.xml
2. You run the plugin on azure-openrewrite using the command: ../sdk/tools> mvn com.azure:azure-openrewrite-compiler-maven-plugin:compile-golden-image -f ./azure-openrewrite/pom.xml

Troubleshooting

Potential Gotchas