Skip to content

Move documentation examples off source-available recipes #539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MBoegers wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Move documentation examples off source-available recipes #539

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5d9da3d
Use Apache-licensed recipes in the onboarding guides
MBoegers Sep 2, 2026
41071b7
Use Apache-licensed recipes in the styles and reference examples
MBoegers Sep 2, 2026
dd7209f
Flag the source-available modules used by the recipe customization guide
MBoegers Sep 2, 2026
54134cb
Add missing CGP warning
mike-solomon Sep 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 21 additions & 5 deletions docs/concepts-and-explanations/styles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")
}
```
</TabItem>

Expand All @@ -186,13 +195,20 @@ Update your `pom.xml` file to include an `<activeStyles>` such as in:
<version>{{VERSION_REWRITE_MAVEN_PLUGIN}}</version>
<configuration>
<activeRecipes>
<!-- Recipes here -->
<recipe>org.openrewrite.java.jackson.UpgradeJackson_2_3</recipe>
</activeRecipes>
<activeStyles>
<!-- This style is made up to have an example. It isn't packaged with OpenRewrite -->
<style>com.yourorg.YesTabsNoStarImports</style>
</activeStyles>
</configuration>
<dependencies>
<dependency>
<groupId>org.openrewrite.recipe</groupId>
<artifactId>rewrite-jackson</artifactId>
<version>{{VERSION_ORG_OPENREWRITE_RECIPE_REWRITE_JACKSON}}</version>
</dependency>
</dependencies>
</plugin>
</plugins>
```
Expand All @@ -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).
Expand Down
10 changes: 5 additions & 5 deletions docs/reference/gradle-plugin-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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")
}
```

Expand Down
14 changes: 7 additions & 7 deletions docs/reference/yaml-format-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
8 changes: 8 additions & 0 deletions docs/running-recipes/customize-recipe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.

<MsalNotice module={[
'org.openrewrite.recipe:rewrite-static-analysis',
'org.openrewrite.recipe:rewrite-spring',
'org.openrewrite.recipe:rewrite-migrate-java',
]} />

## 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.
Expand Down
30 changes: 15 additions & 15 deletions docs/running-recipes/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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:

Expand All @@ -444,22 +444,22 @@ After doing that, your `pom.xml` file should look similar to this:
<activeRecipes>
<recipe>org.openrewrite.java.OrderImports</recipe>
<recipe>com.yourorg.VetToVeterinary</recipe>
<recipe>org.openrewrite.java.spring.boot2.SpringBoot2JUnit4to5Migration</recipe>
<recipe>org.openrewrite.java.jackson.UpgradeJackson_2_3</recipe>
</activeRecipes>
</configuration>
<dependencies>
<dependency>
<groupId>org.openrewrite.recipe</groupId>
<artifactId>rewrite-spring</artifactId>
<version>{{VERSION_ORG_OPENREWRITE_RECIPE_REWRITE_SPRING}}</version>
<artifactId>rewrite-jackson</artifactId>
<version>{{VERSION_ORG_OPENREWRITE_RECIPE_REWRITE_JACKSON}}</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
```

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.

@mike-solomon mike-solomon Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The spring petclinic project that we are using as an example here does not have Jackson in it. If someone ran the stuff being suggested in this guide, they won't actually see any of the changes we're claiming they will see.

We need to do one of these:

  1. Pick a new recipe that makes sense for the project OR
  2. Point to a different sample repository other than spring petclinic OR
  3. Update the documentation to be clearer that they need to run this against their own repo that has Jackson or whatnot

I feel like it would be best to make it so someone could go through this guide and see the changes in a repo we've given them. I can't find any recipe that would work well here, though. Maybe that's something you can help with?

@MBoegers MBoegers Sep 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch! How do you feel about adding a Jackson using class to the openrewrite/spring-petclinic-migration used in this guide?
We own this project anyway.

@mike-solomon mike-solomon Sep 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea! Fine by me.

@MBoegers MBoegers Sep 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll go head and add one

@MBoegers MBoegers Sep 4, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed — nothing in the sample used Jackson, so the recipe ran and changed nothing.

Added it to the sample instead: openrewrite/spring-petclinic-migration#8. With that in place, Step 6 rewrites eleven things across VetSerializer.java and pom.xml.

@mike-solomon mike-solomon Sep 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool - anything you'd change in here to reflect that? If not feel free to merge in whenever.


:::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.
Expand All @@ -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.**

Expand All @@ -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
}
Expand All @@ -515,23 +515,23 @@ 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
}
```
</TabItem>
</Tabs>

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

Expand Down
6 changes: 3 additions & 3 deletions ...nning-recipes/running-rewrite-on-a-maven-project-without-modifying-the-build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
24 changes: 17 additions & 7 deletions src/components/MsalNotice.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
<Admonition
type="info"
title={
<span className={styles.title}>Source available recipe module</span>
<span className={styles.title}>Source available recipe {noun}</span>
}>
<p>
This guide uses <code>{module}</code>, a Moderne{' '}
This guide uses
{modules.map((name, i) => (
<React.Fragment key={name}>
{i === 0 ? ' ' : i === modules.length - 1 ? ' and ' : ', '}
<code>{name}</code>
</React.Fragment>
))}
{plural ? ', Moderne ' : ', a Moderne '}
<a href="https://docs.moderne.io/licensing/moderne-source-available-license/">
source-available
</a>{' '}
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{' '}
<a href="https://codegenomeproject.org/recipes">Code Genome Project</a>. 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.
</p>
</Admonition>
);
Expand Down