rewrite-docs icon indicating copy to clipboard operation
rewrite-docs copied to clipboard

Published 20 hours ago • verified publisher icon openrewrite

Highlight community maintained recipes outside OpenRewrite org

Open timtebeek opened this issue 2 years ago • 6 comments

Aside from the recipes and use cases that we maintain, the wider community has also adopted OpenRewrite to do their own migrations. Notable instances of these are:

Would be good to showcase these in some way in the documentation; I'm thinking a link just beneath the Recipe catalog link, that leads to a page with a bit of detail about each of these projects, and how they are using OpenRewrite. Possibly with a link inviting other projects to add themselves to the list with a pull request, such that it can grow over time.

That way we can show there's more to OpenRewrite than just what we maintain; plus it highlights that it has proven well enough to work for VMWare, Red Hat, AtomicJar, etc... that should tell people evaluation the project something as well.

Then perhaps in the future this can grow to encompass compatibility tests around our / their releases, and inclusion of compatible recipe collections in the SaaS. But all that can follow; a documentation page should do for now.

timtebeek avatar Feb 06 '23 20:02 timtebeek

I'm wondering if it'd make sense to add these community maintained recipes to the rewrite-recipe-markdown-generator 🤔 Any thoughts there @mike-solomon ?

timtebeek avatar Mar 13 '23 13:03 timtebeek

Would you mind expanding on what you mean by add these to the markdown generator @timtebeek ? If we are just making a page with links and a blurb, I’m not sure I see a need for automation on that front. It might be confusing to others if they edit the community page and then it gets overwritten. But maybe I’m missing something?

mike-solomon avatar Mar 13 '23 13:03 mike-solomon

Sure so for instance Axon Framework now has migration recipes: https://central.sonatype.com/artifact/org.axonframework/axon-migration/4.7.3

If we were to add implementation("org.axonframework:axon-migration:4.7.3") to https://github.com/openrewrite/rewrite-recipe-markdown-generator/blob/main/build.gradle.kts then those recipes would also show up in docs.openrewrite.org.

There's some potential for confusion about which are community maintained, and which are OpenRewrite recipes. Some kind of note or label might be in order. Also not sure how these would tie in with the current categories, which might need attention.

timtebeek avatar Mar 13 '23 14:03 timtebeek

@timtebeek I didn't see any recipes in the public SaaS that matched Axon. Are community recipes like these not available in the SaaS or am I just searching for the wrong thing?

If these community recipes aren't available in the SaaS, I feel like we shouldn't add them in the same section as the other recipes. Perhaps an entirely different tab with instructions for how to work with them.

mike-solomon avatar Mar 13 '23 14:03 mike-solomon

From Slack discussions - another point to consider:

Some of the code we have will not work out of the box for external recipes. For instance, GitHub recipe links won't work as we've hard coded that to be very specific to OpenRewrite. I imagine other things may not work as well. If we did decide to add external recipes, some research would need to be done into what works and what we should change.

mike-solomon avatar Mar 13 '23 15:03 mike-solomon

As of recently we've started including some external recipe modules in rewrite-third-party, and from there add them to the generated documentation.

  • https://github.com/openrewrite/rewrite-recipe-markdown-generator/pull/118

We can evaluate and expand the above to include more recipes as helpful to our users.

timtebeek avatar Jun 19 '24 12:06 timtebeek