search

openrewrite / rewrite-docs

Stores the markdown documents used to generate docs.openrewrite.org
https://docs.openrewrite.org
Apache License 2.0
39 stars 42 forks source link

Highlight community maintained recipes outside OpenRewrite org #131

Open timtebeek opened 1 year ago

timtebeek commented 1 year ago

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 commented 1 year ago

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 ?

mike-solomon commented 1 year ago

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?

timtebeek commented 1 year ago

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.

mike-solomon commented 1 year ago

@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 commented 1 year ago

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.

timtebeek commented 2 weeks ago

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

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