Document the Java level that should be used when running Java upgrade recipes

[geoghegk]

What problem are you trying to solve?

I am unclear what version of Java I should be using when running Java Upgrade recipes. Should it be the source level Java that I am upgrading from, or the target level that I am upgrading to?

Describe the solution you'd like

I would like to see clear documentation on which Java level should be used when running Java upgrade recipes - What version of Java should be on the PATH and used by mvn when running the recipes.

For example, if I am running the full set of recipes that would take me from Java 8 to Java 21

org.openrewrite.java.migrate.Java8toJava11
org.openrewrite.java.migrate.UpgradeToJava17
org.openrewrite.java.migrate.UpgradeToJava21

My confusion relates to whether or not some recipes would depend on type resolution in order to work. For example, if a recipe requires type resolution of a type that is newly added in Java 21, then Java 21 would need to be used (or maybe the java 21 rt.jar would need to be on the classpath). Likewise, if a recipe requires type resolution of a type that existed in Java 8 but was removed in Java 21, then Java 8 would need to be used

Should we favor source or target Java level - is one more likely than another to be successful?
Is there any way to identify individual recipes that might need one or the other Java?

Given that in a default configuration, recipes run post compile, I might expect that the source Java level should be used - the target level cannot be used until after the recipes have done their thing to update the code.
We could get around this by either changing the phase where the recipes are run, or, doing a compile on the source level first - so that a new compile is not triggered when we run the recipes. That switching is a bit clunky.