failOnInvalidActiveRecipes is not documented

[francisoud]

What problem are you trying to solve?

The failOnInvalidActiveRecipes option is not documented (maven and gradle). Fro example I'm referring to this line in the gradle plugin: https://github.com/openrewrite/rewrite-gradle-plugin/blob/main/plugin/src/main/java/org/openrewrite/gradle/RewriteExtension.java#L72

gradle.properties

systemProp.rewrite.failOnInvalidActiveRecipes=true

build.gradle:

dependencies {
        // missing dependency
	// rewrite("org.openrewrite.recipe:rewrite-spring:5.21.0")
}

---
type: specs.openrewrite.org/v1beta/recipe
name: my.Migration
displayName: Upgrade code and dependencies
recipeList:
  - org.openrewrite.java.migrate.UpgradeToJava17
  - org.openrewrite.java.spring.boot3.SpringBoot3BestPractices

gradlew rewriteRun
...
> Task :rewriteRun
Validating active recipes
Recipe validation error in initialization: DeclarativeRecipe must not contain uninitialized recipes. Be sure to call .initialize() on DeclarativeRecipe.
Recipe validation error in my.Migration.recipeList[2] (in file:/.../rewrite.yml): recipe 'org.openrewrite.java.spring.boot3.SpringBoot3BestPractices' does 
not exist.

mvn -U -ntp org.openrewrite.maven:rewrite-maven-plugin:run \
-Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE,org.openrewrite.recipe:rewrite-testing-frameworks:RELEASE,org.openrewrite.recipe:rewrite-spring:RELEASE,org.openrewrite.recipe:rewrite-logging-frameworks:RELEASE \
-Drewrite.failOnInvalidActiveRecipes=true

Describe the solution you'd like

I think updating this 2 pages should be enough: https://docs.openrewrite.org/reference/gradle-plugin-configuration https://docs.openrewrite.org/reference/rewrite-maven-plugin

along with other available options

Have you considered any alternatives or workarounds?

I looked into source code but not many people will do it ;)

Additional context

None

Are you interested in contributing this feature to OpenRewrite?

Not for the moment

[timtebeek]

Thanks for pointing this out! Indeed it's hard to keep the plugin documentation updated when it's not automatically generated; for the Maven plugin we have an alternative in the form of: https://openrewrite.github.io/rewrite-maven-plugin/run-mojo.html#failOnInvalidActiveRecipes For the Gradle plugin I'm not aware of any plugin to generate plugin documentation, but perhaps I'm just not fully caught up there; any pointers appreciated!

[mike-solomon]

I went to document this and I started by testing this property with Gradle and Maven. Unfortunately, I'm getting some strange results. This property doesn't appear to work for Gradle projects unless I'm doing something wrong.

If I create a gradle.properties file and set systemProp.rewrite.failOnInvalidActiveRecipes=false in that file, I can see that I don't get any different results regardless of whether I set that to true/false.

For instance, an improperly configured recipe will always result in: Recipe validation errors detected as part of one or more activeRecipe(s). Execution will continue regardless.

I also tried setting this property via the command line such as in: ./gradlew rewriteDryRun -Prewrite.failOnInvalidActiveRecipes=true -- but that didn't do anything either.

On the flip side, for a Maven project, if I pass in -Drewrite.failOnInvalidActiveRecipes=true to the rewrite:run, I correctly see the recipe not being executed when improperly configured.

It's unclear to me if I'm just doing something wrong or if something is broken. I reached out internally to see if anyone might have any ideas.

For now, I'll mark this as blocked as I don't want to try and document something that I can't get working on my own.

If/when I figure this out or get an answer, I'll come back to documenting this.