diff --git a/docs/concepts-and-explanations/styles.md b/docs/concepts-and-explanations/styles.md index 5acf6afeb1..78fee4cd51 100644 --- a/docs/concepts-and-explanations/styles.md +++ b/docs/concepts-and-explanations/styles.md @@ -160,13 +160,22 @@ To enable a style so that it is used for any formatting performed by an OpenRewr Update your `build.gradle` file to include an `activeStyle` such as in: +:::info +`rewrite-jackson` is distributed through the [Code Genome Project](https://artifacts.codegenomeproject.org/maven), which requires authentication. The snippet below assumes you have already declared that repository and added your credentials, as described in the [quickstart guide](../running-recipes/getting-started.md#step-2-add-rewrite-maven-plugin-or-rewrite-gradle-plugin-to-your-project). +::: + ```groovy title="build.gradle" rewrite { - activeRecipe("someRecipe") + activeRecipe("org.openrewrite.java.jackson.UpgradeJackson_2_3") // This style is made up to have an example. activeStyle("com.yourorg.YesTabsNoStarImports") } + +dependencies { + rewrite(platform("org.openrewrite.recipe:rewrite-recipe-bom:latest.release")) + rewrite("org.openrewrite.recipe:rewrite-jackson") +} ``` @@ -186,13 +195,20 @@ Update your `pom.xml` file to include an `` such as in: {{VERSION_REWRITE_MAVEN_PLUGIN}} - + org.openrewrite.java.jackson.UpgradeJackson_2_3 + + + org.openrewrite.recipe + rewrite-jackson + {{VERSION_ORG_OPENREWRITE_RECIPE_REWRITE_JACKSON}} + + ``` @@ -204,9 +220,9 @@ Add a `-Drewrite.activeStyles` parameter to your Maven command in the terminal s ```bash mvn -U org.openrewrite.maven:rewrite-maven-plugin:{{VERSION_REWRITE_MAVEN_PLUGIN}}:run \ - -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-static-analysis:RELEASE \ - -Drewrite.activeRecipes=org.openrewrite.staticanalysis.CommonStaticAnalysis \ - -Drewrite.activeStyles=org.some.style.name + -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-jackson:RELEASE \ + -Drewrite.activeRecipes=org.openrewrite.java.jackson.UpgradeJackson_2_3 \ + -Drewrite.activeStyles=com.yourorg.YesTabsNoStarImports ``` Since this command doesn't modify your `pom.xml`, the Code Genome Project repository has to be declared in your Maven `settings.xml` file as both a `pluginRepository` and a `repository`, as described in [running Rewrite without modifying the build](/running-recipes/running-rewrite-on-a-maven-project-without-modifying-the-build#configure-the-code-genome-project-repository). diff --git a/docs/reference/gradle-plugin-configuration.md b/docs/reference/gradle-plugin-configuration.md index 9277739ad5..65b20c6bcf 100644 --- a/docs/reference/gradle-plugin-configuration.md +++ b/docs/reference/gradle-plugin-configuration.md @@ -157,11 +157,11 @@ No recipe is ever run on your codebase without being explicitly activated in the ```groovy title="build.gradle" dependencies { rewrite(platform("org.openrewrite.recipe:rewrite-recipe-bom:latest.release")) - rewrite("org.openrewrite.recipe:rewrite-spring") + rewrite("org.openrewrite.recipe:rewrite-jackson") } ``` -Once a pre-packaged recipe has been added to the `rewrite` dependency configuration, you can tell the Gradle plugin to activate it the `rewrite` DSL. For example, here is how you would activate the `org.openrewrite.java.testing.junit5.JUnit5BestPractices` recipe that comes with `rewrite-testing-frameworks` in a single-project Gradle build: +Once a pre-packaged recipe has been added to the `rewrite` dependency configuration, you can tell the Gradle plugin to activate it the `rewrite` DSL. For example, here is how you would activate the `org.openrewrite.java.jackson.UpgradeJackson_2_3` recipe that comes with `rewrite-jackson` in a single-project Gradle build: ```groovy title="build.gradle" plugins { @@ -181,13 +181,13 @@ repositories { } dependencies { - testImplementation("junit:junit:4.13") + implementation("com.fasterxml.jackson.core:jackson-databind:2.18.2") rewrite(platform("org.openrewrite.recipe:rewrite-recipe-bom:latest.release")) - rewrite("org.openrewrite.recipe:rewrite-testing-frameworks") + rewrite("org.openrewrite.recipe:rewrite-jackson") } rewrite { - activeRecipe("org.openrewrite.java.testing.junit5.JUnit5BestPractices") + activeRecipe("org.openrewrite.java.jackson.UpgradeJackson_2_3") } ``` diff --git a/docs/reference/yaml-format-reference.md b/docs/reference/yaml-format-reference.md index cff7636f6f..e57d819c18 100644 --- a/docs/reference/yaml-format-reference.md +++ b/docs/reference/yaml-format-reference.md @@ -170,24 +170,24 @@ In this example, if a file matches `**/my.json` OR `**/your.json*` OR `**/our.js A common mistake new users make is to assume that if a precondition matches any file, then the recipe will apply to the entire repository. -For example, you might be tempted to use `FindPlugins` as a precondition for `CommonStaticAnalysis` with the idea that you only want static analysis fixes on Gradle projects that apply a specific plugin. +For example, you might be tempted to use `FindPlugins` as a precondition for `RemoveUnusedImports` with the idea that you only want unused imports removed on Gradle projects that apply a specific plugin. -However, if you were to do this, you wouldn't get the results you expected as the `FindPlugins` recipe flags the plugin in `build.gradle` files. In other words, the `CommonStaticAnalysis` recipe would only be run against those `build.gradle` files. +However, if you were to do this, you wouldn't get the results you expected as the `FindPlugins` recipe flags the plugin in `build.gradle` files. In other words, the `RemoveUnusedImports` recipe would only be run against those `build.gradle` files. Fortunately, there are recipes that _can_ be used in this type of situation. For instance, the `ModuleHasPlugin` recipe will mark _all_ files within a project if a specific plugin is found: ```yaml type: specs.openrewrite.org/v1beta/recipe -name: org.sample.FixedSonarStaticAnalysis -displayName: Fix sonar issues -description: >- - This recipe applies common static analysis issues only to gradle projects that apply the sonar plugin. +name: org.sample.CleanUpSonarProjects +displayName: Remove unused imports in sonar projects +description: >- + This recipe removes unused imports only in gradle projects that apply the sonar plugin. This works because ModuleHasPlugin will mark all files within a project that applies the plugin. preconditions: - org.openrewrite.gradle.search.ModuleHasPlugin: pluginId: org.sonarqube recipeList: - - org.openrewrite.staticanalysis.CommonStaticAnalysis + - org.openrewrite.java.RemoveUnusedImports ``` It isn't obvious from just the names of the recipes that `FindPlugins` and `ModuleHasPlugin` behave differently. Because of that, the best way for you to know whether a particular recipe is suitable as a precondition or not is to run that recipe on its own. diff --git a/docs/running-recipes/customize-recipe.md b/docs/running-recipes/customize-recipe.md index b5810bbd26..06f9e745bb 100644 --- a/docs/running-recipes/customize-recipe.md +++ b/docs/running-recipes/customize-recipe.md @@ -3,6 +3,8 @@ sidebar_label: Customizing recipes description: How to customize recipes to meet your needs. --- +import MsalNotice from '@site/src/components/MsalNotice'; + # How to customize recipes to meet your needs OpenRewrite recipes are **opinionated** – meaning that they encourage certain conventions, patterns, or practices. The idea behind this is to provide sensible defaults that work for _most_ people _most_ of the time without requiring any fiddling. @@ -13,6 +15,12 @@ Fortunately, in many cases, recipes can be easily modified, broken apart, or com In this guide, we'll walk you through how to do this. + + ## Customizing a recipe For the sake of this guide, let's assume that you took a look at the [Common static analysis issues recipe](../recipes/staticanalysis/commonstaticanalysis.md) and decided that you don't like the fact that it [disallows multiple variables from being declared on the same line](../recipes/staticanalysis/multiplevariabledeclarations.md). You want to remove that recipe from the list of recipes being executed – but you still want to run all of the other ones. diff --git a/docs/running-recipes/getting-started.md b/docs/running-recipes/getting-started.md index fccd0eacc6..372786e85e 100644 --- a/docs/running-recipes/getting-started.md +++ b/docs/running-recipes/getting-started.md @@ -413,13 +413,13 @@ From there, you can confirm that everything still builds and passes its tests by ## Step 6: Running Recipes from External Modules -At this point, you know how to configure and run any recipe included in OpenRewrite itself. However, many recipes are not bundled into the core library. For example, all of the Spring, Mockito, JUnit, and AssertJ-related recipes maintained by the OpenRewrite team live in the [rewrite-spring repository](https://github.com/openrewrite/rewrite-spring). +At this point, you know how to configure and run any recipe included in OpenRewrite itself. However, many recipes are not bundled into the core library. For example, the Jackson recipes maintained by the OpenRewrite team live in the [rewrite-jackson repository](https://github.com/openrewrite/rewrite-jackson), the testing ones in [rewrite-testing-frameworks](https://github.com/openrewrite/rewrite-testing-frameworks), and the Spring ones in [rewrite-spring](https://github.com/openrewrite/rewrite-spring). :::info You can search through all of the recipes in the [OpenRewrite docs](/recipes). Each recipe page has instructions for how to import the recipe and what parameters (if any) need to be included. ::: -Let's pretend that you want to migrate JUnit 4 to JUnit 5 in a Spring project you have. If you take a look at the [Usage section](../recipes/java/spring/boot2/springboot2junit4to5migration.md#usage) in the [JUnit 4 to 5 migration recipe](../recipes/java/spring/boot2/springboot2junit4to5migration.md), you'll see what you need to include in your `build.gradle(.kts)` or `pom.xml` file in order to use this recipe. +Let's pretend that you want to migrate a project from Jackson 2.x to Jackson 3.x. If you take a look at the [Usage section](../recipes/java/jackson/upgradejackson_2_3.md#usage) in the [Jackson 2.x to 3.x migration recipe](../recipes/java/jackson/upgradejackson_2_3.md), you'll see what you need to include in your `build.gradle(.kts)` or `pom.xml` file in order to use this recipe. Below, we'll walk through the [Maven](#maven--external-modules) and [Gradle](#gradle--external-modules) changes and provide some additional context around said changes. @@ -428,8 +428,8 @@ Below, we'll walk through the [Maven](#maven--external-modules) and [Gradle](#gr For Maven projects, you'll need to: * Add the recipe to the `activeRecipes` list -* Add a dependency on the library where the desired recipe lives (JUnit 4 to 5 lives in the [rewrite-spring](https://github.com/openrewrite/rewrite-spring) repository) -* Specify a version of `rewrite-spring` to use +* Add a dependency on the library where the desired recipe lives (the Jackson migration lives in the [rewrite-jackson](https://github.com/openrewrite/rewrite-jackson) repository) +* Specify a version of `rewrite-jackson` to use After doing that, your `pom.xml` file should look similar to this: @@ -444,14 +444,14 @@ After doing that, your `pom.xml` file should look similar to this: org.openrewrite.java.OrderImports com.yourorg.VetToVeterinary - org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration + org.openrewrite.java.jackson.UpgradeJackson_2_3 org.openrewrite.recipe - rewrite-spring - {{VERSION_ORG_OPENREWRITE_RECIPE_REWRITE_SPRING}} + rewrite-jackson + {{VERSION_ORG_OPENREWRITE_RECIPE_REWRITE_JACKSON}} @@ -459,7 +459,7 @@ After doing that, your `pom.xml` file should look similar to this: ``` -To double-check that everything is working, run the command `mvn rewrite:run`. Your project should be upgraded to Spring Boot 2 and all of the test classes should be updated to JUnit 5. Your `pom.xml` file will also have had its Spring dependencies updated, the JUnit 4 dependency removed, and the JUnit 5 dependency added. +To double-check that everything is working, run the command `mvn rewrite:run`. Your project's Jackson imports and API usages should be migrated from 2.x to 3.x. Your `pom.xml` file will also have had its Jackson dependencies updated to the 3.x coordinates. :::info Maven does not currently support using a bill of materials (BOM) to specify plugin versions or dependencies. This means that you will have to specify the versions of each plugin by hand, unlike in the Gradle section below. @@ -470,7 +470,7 @@ Maven does not currently support using a bill of materials (BOM) to specify plug Unlike Maven projects, Gradle projects have two options for specifying recipe versions. You can: 1. Add `rewrite-recipe-bom` as a [bill of materials (BOM) dependency](https://docs.gradle.org/current/userguide/platforms.html#sub:bom\_import) -2. Add the specific dependency and version that you want (in this case `rewrite-spring`) +2. Add the specific dependency and version that you want (in this case `rewrite-jackson`) If you choose to use the `rewrite-recipe-bom`, you won't have to worry about specifying versions for your OpenRewrite recipes as all of the recipes you include in your `dependencies` section will have an appropriate version specified in the bill of materials (BOM). **For Gradle projects, this is the recommended approach.** @@ -491,13 +491,13 @@ Presuming you chose to use the `rewrite-recipe-bom`, your Gradle setup should lo activeRecipe( 'org.openrewrite.java.OrderImports', 'com.yourorg.VetToVeterinary', - 'org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration' + 'org.openrewrite.java.jackson.UpgradeJackson_2_3' ) } dependencies { rewrite platform('org.openrewrite.recipe:rewrite-recipe-bom:latest.release') - rewrite('org.openrewrite.recipe:rewrite-spring') + rewrite('org.openrewrite.recipe:rewrite-jackson') // Other project dependencies } @@ -515,13 +515,13 @@ Presuming you chose to use the `rewrite-recipe-bom`, your Gradle setup should lo activeRecipe( "org.openrewrite.java.OrderImports", "com.yourorg.VetToVeterinary", - "org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration" + "org.openrewrite.java.jackson.UpgradeJackson_2_3" ) } dependencies { rewrite(platform("org.openrewrite.recipe:rewrite-recipe-bom:latest.release")) - rewrite("org.openrewrite.recipe:rewrite-spring") + rewrite("org.openrewrite.recipe:rewrite-jackson") // Other project dependencies } @@ -529,9 +529,9 @@ Presuming you chose to use the `rewrite-recipe-bom`, your Gradle setup should lo -To check that everything worked correctly, run the command `gradle rewriteRun`. You should see that the project has been upgraded to Spring Boot 2 and all of the test classes have been updated to JUnit 5. +To check that everything worked correctly, run the command `gradle rewriteRun`. You should see that the project's Jackson imports and API usages have been migrated from 2.x to 3.x. -OpenRewrite edits Gradle build files as well as source code, so your `build.gradle(.kts)` should have had its Spring and JUnit dependencies updated too. Recipes such as [AddDependency](../recipes/gradle/adddependency.md), [ChangeDependency](../recipes/gradle/changedependency.md), and [UpgradeDependencyVersion](../recipes/gradle/upgradedependencyversion.md) handle this, and migration recipes compose them. +OpenRewrite edits Gradle build files as well as source code, so your `build.gradle(.kts)` should have had its Jackson dependencies updated too. Recipes such as [AddDependency](../recipes/gradle/adddependency.md), [ChangeDependency](../recipes/gradle/changedependency.md), and [UpgradeDependencyVersion](../recipes/gradle/upgradedependencyversion.md) handle this, and migration recipes compose them. ## Next steps diff --git a/docs/running-recipes/running-rewrite-on-a-maven-project-without-modifying-the-build.md b/docs/running-recipes/running-rewrite-on-a-maven-project-without-modifying-the-build.md index 53fe017f80..63006b1e3e 100644 --- a/docs/running-recipes/running-rewrite-on-a-maven-project-without-modifying-the-build.md +++ b/docs/running-recipes/running-rewrite-on-a-maven-project-without-modifying-the-build.md @@ -63,12 +63,12 @@ mvn -U org.openrewrite.maven:rewrite-maven-plugin:{{VERSION_REWRITE_MAVEN_PLUGIN -Drewrite.activeRecipes=org.openrewrite.java.RemoveUnusedImports ``` -If the recipe comes from a different library (such as with [Migrate to Jakarta EE 9](../recipes/java/migrate/jakarta/javaxmigrationtojakarta.md)) then you can run the following command and replace `org.openrewrite.recipe:rewrite-migrate-java:RELEASE` with the artifact coordinates of your recipe and `org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta` with the path to the recipe you're wanting to run: +If the recipe comes from a different library (such as with [Migrate from Jackson 2.x to Jackson 3.x](../recipes/java/jackson/upgradejackson_2_3.md)) then you can run the following command and replace `org.openrewrite.recipe:rewrite-jackson:RELEASE` with the artifact coordinates of your recipe and `org.openrewrite.java.jackson.UpgradeJackson_2_3` with the path to the recipe you're wanting to run: ```shell mvn -U org.openrewrite.maven:rewrite-maven-plugin:{{VERSION_REWRITE_MAVEN_PLUGIN}}:run \ - -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE \ - -Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta + -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-jackson:RELEASE \ + -Drewrite.activeRecipes=org.openrewrite.java.jackson.UpgradeJackson_2_3 ``` ## Running a recipe with configuration parameters diff --git a/src/components/MsalNotice.tsx b/src/components/MsalNotice.tsx index 693ea5ecf9..00414ffcef 100644 --- a/src/components/MsalNotice.tsx +++ b/src/components/MsalNotice.tsx @@ -3,29 +3,39 @@ import Admonition from '@theme/Admonition'; import styles from './MsalNotice.module.css'; interface MsalNoticeProps { - /** Full `groupId:artifactId` of the source-available module this guide depends on. */ - module: string; + /** Full `groupId:artifactId` of each source-available module this guide depends on. */ + module: string | string[]; } /** - * Flags that a guide depends on a source-available module, which the Code Genome + * Flags that a guide depends on source-available modules, which the Code Genome * Project serves to Moderne customers only. */ export default function MsalNotice({module}: MsalNoticeProps): JSX.Element { + const modules = Array.isArray(module) ? module : [module]; + const plural = modules.length > 1; + const noun = plural ? 'modules' : 'module'; return ( Source available recipe module + Source available recipe {noun} }>

- This guide uses {module}, a Moderne{' '} + This guide uses + {modules.map((name, i) => ( + + {i === 0 ? ' ' : i === modules.length - 1 ? ' and ' : ', '} + {name} + + ))} + {plural ? ', Moderne ' : ', a Moderne '} source-available {' '} - recipe module. Compiled binaries are only available to Moderne customers, hosted at the{' '} + recipe {noun}. Compiled binaries are only available to Moderne customers, hosted at the{' '} Code Genome Project. For non-commercial - use you can compile and publish the recipe module locally to use the recipes. + use you can compile and publish the recipe {noun} locally to use the recipes.

);