Confusion around applicability tests in yaml recipes

[timtebeek]

Our current documentation around yaml applicability tests might contain slight imperfections that lead to confusion in an issue and pull request last week:

1. should anySource match when any or all of the argument recipes match any file?
   Replace Mockito 1.x any(Class) and anyString() with nullable(Class) rewrite-testing-frameworks#320

2. should FindSourceFiles be used to limit applicability to specific files, or should one use HasSourcePath instead?
   Singlesource applicability with FindSourceFiles now applies changes to all files rewrite#2919

Should be good to clear these up, as they lead to questions and debugging currently.

[shanman190]

@timtebeek, the way that this was explained to me was that it is logical AND all around.

So to be explicit:

applicability:
  anySource:
    - com.example.A
    - com.example.B

The above only applies if both are true. If one of them is false, then the recipe does not apply. This works the same for single source and a combination of single source and any source.

[timtebeek]

Thanks! That's what I gathered from the code and in practice as well; My issue here is mostly with the phrasing in the current documentation. I'd suggest a change similar to this:

If the anySource list is specified, OpenRewrite will run every recipe in the anySource list on every file in the repository the recipe is being run on. If any of those recipes result in a change to at least one file, then the declarative recipe is considered "applicable" for that repository and the recipes specified in the recipeList will be run on every file in the repository.

If the anySource list is specified, OpenRewrite will run every recipe in the anySource list on every file in the repository the recipe is being run on. If all of those recipes result in a change to at least one file, then the declarative recipe is considered "applicable" for that repository and the recipes specified in the recipeList will be run on every file in the repository.

It's a small change, but nuanced and prevents confusion, especially with non-native English speakers like myself.

And then the second case is to swap out the FindSourceFiles example for HasSourcePath, which appears closer to what's intended. Happy to make these changes if we agree they improve the docs.

[shanman190]

So as described in the FindSourceFiles ticket as well, that recipe should have worked for their use case, but unfortunately there was a bug with single source applicability which Kun fixed in the range that you provided. I think either is equally useable, it's just going to depend on if you want to modify everything in a folder (FindSourcePath) vs modify files with this path+name (FindSourceFiles).

[mike-solomon]

I'm going to close this ticket as I think this no longer applies. YAML recipes no longer work with applicability tests. If I've misunderstood please let me know and feel free to reopen.