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

Provide a way to easily find correct versions alignments #186

Open ia3andy opened 1 year ago

ia3andy commented 1 year ago

What problem are you trying to solve?

As explained on Slack, https://rewriteoss.slack.com/archives/C01AB6L98TC/p1687767750280069:

We have an artifact with dependency on various OpenRewrite modules, this also reference Maven and Gradle plugins version in a property file (to be use to run the yaml/java recipes in that artifact). Then I want to use that artifact from either the Maven or Gradle build plugin using the version of the plugins specified in the properties. but we need to know which versions of the plugins are compatible with the modules used in your artifact

Describe the solution you'd like

Have the Gradle/Maven Rewrite plugins versions aligned with the OpenRewrite core version (at least up to the minor).

Have you considered any alternatives or workarounds?

Yes but there is not a lot of other solutions

Additional context

Link are provided in the description

Are you interested in contributing this feature to OpenRewrite

Sure

timtebeek commented 1 year ago

After some discussion internally we came to the conclusion that the Maven and Gradle plugins version numbers are likely to diverge soon after any alignment, as we are use to develop minor features to build plugins independent of minor versions of OpenRewrite. That for now rules out aligning the versions of the plugins with OpenRewrite, unfortunately.

That leaves open the option to better document the compatible versions of the plugins and OpenRewrite. @mike-solomon is there any support for instance to add tags to openrewrite/rewrite-docs with each new release? Perhaps also going back to the latest 7.x? That way we'd have a snapshot of the different versions of this particular page: https://docs.openrewrite.org/reference/latest-versions-of-every-openrewrite-module latest-versions-of-every-openrewrite-module.md Maybe there's even a way in GitBook to get a version number dropdown going such that we can also document historic versions? That could help to have an easier way to access what historic versions are compatible, since we're not cross-compatible over time.

Open to other suggestions as well; we already capture the rewrite.version with each Maven plugin release for instance; could that be of some use here @ia3andy ?

mike-solomon commented 1 year ago

@timtebeek I don't believe that GitBook supports versioning like that @timtebeek :( - I was looking at Antora with AsciiDoc over here and they both support it if we ever migrate to that.

I think the only two options we really have with GitBook are:

  1. Make a new page for every release (similar to the changelog). We could perhaps add the latest versions to the bottom of the existing changelogs so that we don't have duplicate pages for every release.
  2. Make one giant page that has all of the OpenRewrite versions with the table duplicated/changed for each.

Using tabs wouldn't be feasible as they get really difficult to view or cycle through once there's more than a few. There aren't any other structures that GitBook offers for grouping as far as I can see :(

timtebeek commented 1 year ago

Moved this issue to rewrite-docs, as we will likely end up documenting the compatible versions rather than aligning them.

Unless this earlier suggestion can help

we already capture the rewrite.version with each Maven plugin release for instance; could that be of some use here @ia3andy ?

ia3andy commented 1 year ago

@timtebeek is there a similar capture for gradle?

ia3andy commented 1 year ago

Also, using this solution is fixing our immediate problem (if we have the same for Gradle). Still I think having it in the doc to be consumed in a glimpse by users is a must have.

timtebeek commented 1 year ago

is there a similar capture for gradle?

I think this part does something similar for the Gradle plugin, although it's my first time seeing it. Hope it helps!

Also, using this solution is fixing our immediate problem (if we have the same for Gradle). Still I think having it in the doc to be consumed in a glimpse by users is a must have.

Agree with you there; best to document the compatible versions for posterity, rather than "hide" that in a plugin jar version resource only.

ia3andy commented 1 year ago

is there a similar capture for gradle?

I think this part does something similar for the Gradle plugin, although it's my first time seeing it. Hope it helps!

@timtebeek Can't find the actual version on GH or in the zip, can you?

timtebeek commented 1 year ago

is there a similar capture for gradle?

I think this part does something similar for the Gradle plugin, although it's my first time seeing it. Hope it helps!

@timtebeek Can't find the actual version on GH or in the zip, can you?

I don't have the details there, but it looks like we might have defined the step, but are not yet referencing it anywhere. 🤔 @sambsnyd any idea why we have that generateVersionsProperties task defined but potentially unused?

For context: Andy is looking for a way to determine, from a given Maven/Gradle plugin version, what's the compatible OpenRewrite core version.

ia3andy commented 1 year ago

is there a similar capture for gradle?

I think this part does something similar for the Gradle plugin, although it's my first time seeing it. Hope it helps!

@timtebeek Can't find the actual version on GH or in the zip, can you?

I don't have the details there, but it looks like we might have defined the step, but are not yet referencing it anywhere. 🤔 @sambsnyd any idea why we have that generateVersionsProperties task defined but potentially unused?

For context: Andy is looking for a way to determine, from a given Maven/Gradle plugin version, what's the compatible OpenRewrite core version.

and I guess anyone using the plugins will need this info if they don't want to end up with breakages..