Add links to docs & reference implementations in README.md (#42)

* Add links to docs & reference implementations in README.md

* Inline Gradle wrapper validation

* Format licenses as part of review

* Add missing test for yaml recipe

* Apply suggestion

.github/workflows/ci.yml

@@ -26,6 +26,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - uses: gradle/wrapper-validation-action@v2
       - name: set-up-jdk
         uses: actions/setup-java@v4.0.0
         with:

.github/workflows/receive-pr.yml

@@ -27,6 +27,7 @@ jobs:
         with:
           ref: ${{github.event.pull_request.head.ref}}
           repository: ${{github.event.pull_request.head.repo.full_name}}
+      - uses: gradle/wrapper-validation-action@v2
       - uses: actions/setup-java@v4
         with:
           java-version: '21'
@@ -47,7 +48,7 @@ jobs:
       - name: Apply OpenRewrite best practices
         uses: gradle/actions/setup-gradle@v3
         with:
-          arguments: ${{ env.GRADLE_SWITCHES }} rewriteRun -Drewrite.activeRecipe=org.openrewrite.recipes.OpenRewriteBestPractices
+          arguments: ${{ env.GRADLE_SWITCHES }} licenseFormat rewriteRun -Drewrite.activeRecipe=org.openrewrite.recipes.OpenRewriteBestPractices
 
       # Capture the diff
       - name: Create patch

README.md

@@ -10,11 +10,32 @@ To begin, fork this repository and customize it by:
 2. Changing the `group` in `build.gradle.kts`.
 3. Changing the package structure from `com.yourorg` to whatever you want.
 
-## Detailed Guide
+## Getting started
 
-There is a [comprehensive getting started guide](https://docs.openrewrite.org/authoring-recipes/recipe-development-environment)
+Familiarize yourself with the [OpenRewrite documentation](https://docs.openrewrite.org/), in particular the [concepts & explanations](https://docs.openrewrite.org/concepts-explanations) op topics like the [lossless semantic trees](https://docs.openrewrite.org/concepts-explanations/lossless-semantic-trees), [recipes](https://docs.openrewrite.org/concepts-explanations/recipes) and [visitors](https://docs.openrewrite.org/concepts-explanations/visitors).
+
+You might be interested to watch some of the [videos available on OpenRewrite and Moderne](https://www.youtube.com/@moderne-auto-remediation).
+
+Once you want to dive into the code there is a [comprehensive getting started guide](https://docs.openrewrite.org/authoring-recipes/recipe-development-environment)
 available in the OpenRewrite docs that provides more details than the below README.
 
+## Reference recipes
+
+* [META-INF/rewrite/stringutils.yml](./src/main/resources/META-INF/rewrite/stringutils.yml) - A declarative YAML recipe that replaces usages of `org.springframework.util.StringUtils` with `org.apache.commons.lang3.StringUtils`.
+  - [UseApacheStringUtilsTest](./src/test/java/com/yourorg/UseApacheStringUtilsTest.java) - A test class for the `com.yourorg.UseApacheStringUtils` recipe.
+* [NoGuavaListsNewArrayList.java](./src/main/java/com/yourorg/NoGuavaListsNewArrayList.java) - An imperative Java recipe that replaces usages of `com.google.common.collect.Lists` with `new ArrayList<>()`.
+  - [NoGuavaListsNewArrayListTest.java](./src/test/java/com/yourorg/NoGuavaListsNewArrayListTest.java) - A test class for the `NoGuavaListsNewArrayList` recipe.
+* [SimplifyTernary](./src/main/java/com/yourorg/SimplifyTernary.java) - An Refaster style recipe that simplifies ternary expressions.
+  - [SimplifyTernaryTest](./src/test/java/com/yourorg/SimplifyTernaryTest.java) - A test class for the `SimplifyTernary` recipe.
+* [AssertEqualsToAssertThat](./src/main/java/com/yourorg/AssertEqualsToAssertThat.java) - An imperative Java recipe that replaces JUnit's `assertEquals` with AssertJ's `assertThat`, to show how to handle classpath dependencies.
+  - [AssertEqualsToAssertThatTest](./src/test/java/com/yourorg/AssertEqualsToAssertThatTest.java) - A test class for the `AssertEqualsToAssertThat` recipe.
+* [AppendToReleaseNotes](./src/main/java/com/yourorg/AppendToReleaseNotes.java) - A ScanningRecipe that appends a message to the release notes of a project.
+  - [AppendToReleaseNotesTest](./src/test/java/com/yourorg/AppendToReleaseNotesTest.java) - A test class for the `AppendToReleaseNotes` recipe.
+* [ClassHierarchy](./src/main/java/com/yourorg/ClassHierarchy.java) - A recipe that demonstrates how to produce a data table on the class hierarchy of a project.
+  - [ClassHierarchyTest](./src/test/java/com/yourorg/ClassHierarchyTest.java) - A test class for the `ClassHierarchy` recipe.
+* [UpdateConcoursePipeline](./src/main/java/com/yourorg/UpdateConcoursePipeline.java) - A recipe that demonstrates how to update a Concourse pipeline, as an example of operating on Yaml files.
+  - [UpdateConcoursePipelineTest](./src/test/java/com/yourorg/UpdateConcoursePipelineTest.java) - A test class for the `UpdateConcoursePipeline` recipe.
+
 ## Local Publishing for Testing
 
 Before you publish your recipe module to an artifact repository, you may want to try it out locally.

build.gradle.kts

@@ -16,6 +16,7 @@ dependencies {
     implementation(platform("org.openrewrite.recipe:rewrite-recipe-bom:latest.release"))
 
     implementation("org.openrewrite:rewrite-java")
+    implementation("org.openrewrite.recipe:rewrite-java-dependencies")
     implementation("org.openrewrite:rewrite-yaml")
     implementation("org.assertj:assertj-core:3.24.2")
     runtimeOnly("org.openrewrite:rewrite-java-17")
@@ -34,6 +35,8 @@ dependencies {
 
     // Our recipe converts Guava's `Lists` type
     testRuntimeOnly("com.google.guava:guava:latest.release")
+    testRuntimeOnly("org.apache.commons:commons-lang3:latest.release")
+    testRuntimeOnly("org.springframework:spring-core:latest.release")
 
     // Contains the OpenRewriteBestPractices recipe, which you can apply to your recipes
     rewrite("org.openrewrite.recipe:rewrite-recommendations:latest.release")

src/main/java/com/yourorg/package-info.java

@@ -13,10 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-// We annotate the package to indicate that fields and methods in this package are non-null by default.
 @NonNullApi
 @NonNullFields
 package com.yourorg;
 
+// We annotate the package to indicate that fields and methods in this package are non-null by default.
 import org.openrewrite.internal.lang.NonNullApi;
 import org.openrewrite.internal.lang.NonNullFields;

src/main/resources/META-INF/rewrite/rewrite.yml

@@ -18,20 +18,10 @@
 # https://docs.openrewrite.org/reference/yaml-format-reference
 # These are most easily composed through the Yaml recipe builder at:
 # https://app.moderne.io/recipes/builder
----
-type: specs.openrewrite.org/v1beta/recipe
-name: com.yourorg.RecipeA
-displayName: Recipe A
-description: Applies NoGuavaListsNewArrayList.
-tags:
-  - tag1
-  - tag2
-recipeList:
-  - com.yourorg.NoGuavaListsNewArrayList
----
 
 # Notice how we can have multiple recipes in the same file, separated by `---`
 # You can also have multiple files in `src/main/resources/META-INF/rewrite`, each containing one or more recipes.
+---
 type: specs.openrewrite.org/v1beta/recipe
 name: com.yourorg.UseOpenRewriteNullable
 displayName: Prefer OpenRewrite Nullable

src/main/resources/META-INF/rewrite/stringuitls.yml → src/main/resources/META-INF/rewrite/stringutils.yml

@@ -16,9 +16,9 @@
 
 ---
 type: specs.openrewrite.org/v1beta/recipe
-name: com.example.UseApacheStringUtils
-displayName: Use apache string utils
-description: Replace Spring string utilities with apache string utilities
+name: com.yourorg.UseApacheStringUtils
+displayName: Use Apache `StringUtils`
+description: Replace Spring string utilities with Apache string utilities
 recipeList:
   - org.openrewrite.java.dependencies.AddDependency:
       groupId: org.apache.commons

src/test/java/com/yourorg/UseApacheStringUtilsTest.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2024 the original author or authors.
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.yourorg;
+
+import org.junit.jupiter.api.Test;
+import org.openrewrite.DocumentExample;
+import org.openrewrite.java.JavaParser;
+import org.openrewrite.test.RecipeSpec;
+import org.openrewrite.test.RewriteTest;
+
+import static org.openrewrite.java.Assertions.java;
+
+class UseApacheStringUtilsTest implements RewriteTest {
+    @Override
+    public void defaults(RecipeSpec spec) {
+        spec.recipeFromResources("com.yourorg.UseApacheStringUtils")
+          .parser(JavaParser.fromJavaVersion().classpath("commons-lang3", "spring-core"));
+    }
+
+    @DocumentExample
+    @Test
+    void replacesStringEquals() {
+        rewriteRun(
+          //language=java
+          java(
+            """
+              import org.springframework.util.StringUtils;
+              
+              class A {
+                  boolean test(String s) {
+                      return StringUtils.containsWhitespace(s);
+                  }
+              }
+              """,
+            """
+              import org.apache.commons.lang3.StringUtils;
+              
+              class A {
+                  boolean test(String s) {
+                      return StringUtils.containsWhitespace(s);
+                  }
+              }
+              """
+          )
+        );
+    }
+}