Is semver followed diligently in libraries and tools?

[crankydillo]

Can I safely do minor upgrades of the rewrite-maven-plugin without worrying about it breaking anything? Is that generally the case for rewrite libraries?

For example, we have a few recipes that compile against rewrite-bom:8.x. We are currently using rewrite-maven-plugin:5.39.2, which compiled against rewrite-bom:8.34.0. I'm wondering if we can safely upgrade rewrite-maven-plugin:5.x minor releases and continue to use them with all recipes that were built against rewrite-bom:8.x.

Understand that mistakes can always happen. I'm just trying to understand versioning policy. I did search end user docs for 'semver':)

[timtebeek]

Hi @crankydillo ; Thanks for reaching out. In general I can say we only recommend/support using versions as aligned through out rewrite-recipe-bom releases: https://github.com/openrewrite/rewrite-recipe-bom/releases
Any release there will list which versions of openrewrite/rewrite work well with which plugins and recipe modules; typically the latest of each at the time of release. Using mismatched versions could result in unexpected failures, which semantic versioning wouldn't necessarily guard against well, as you'd still need to update each to the latest release anyway, or risk getting left behind.

As an example we recently switched from using internal nullability annotations to JSpecify, which meant the core of OpenRewrite, the plugins, and all recipe modules are affected. Folks can either still use older versions of each, or exclusively use newer versions, but not use a mix a older and newer versions. Had we classified this as a semver breaking change, and then would have had to release new major versions of everything, whereas in reality this is an implementation detail that folks using aligned versions would not even notice. Were we to strictly semver everything then we'd be in the triple digits for major versions, which isn't particularly reflective of the work put into each release.

As such you're best to use the aligned versions as listed through rewrite-recipe-bom, and only expect new major versions when there's breaking changes to the way OpenRewrite recipes are to be written by downstream projects.

I hope that helps clarify what to do, and what to expect!

[crankydillo]

Ultimately, we compiled our recipes against rewrite-bom:8.x. We are using it via rewrite-maven-plugin:5.x. Ideally, we could continue using our recipe (without new releases) safely throughout the life of rewrite-maven-plugin:5.x, which would bring in backward compatible changes via its own minor/patch releases and whatever it gets safely from rewrite-bom (presumably on the 8.x line).

I guess we'll just assume we're probably safe if we do this, even if we don't re-release our recipe with latest 8.x rewrite-bom. Thoughts?

[timtebeek]

Probably safe is what I'd say as well; If that becomes problematic over time do let us know.

Also quick note: I see you mention rewrite-bom whereas we recommend rewrite-recipe-bom instead; that latter also includes common recipe modules like rewrite-java-dependencies that are released in tandem, but with different versioning schemes. Ideally that reduces your version management down to only rewrite-recipe-bom and rewrite-maven-plugin. That ought to be manageable I'd hope.

[crankydillo]

Thanks Tim.

Also quick note: I see you mention rewrite-bom whereas we recommend rewrite-recipe-bom instead; that latter also includes common recipe modules like rewrite-java-dependencies that are released in tandem, but with different versioning schemes. Ideally that reduces your version management down to only rewrite-recipe-bom and rewrite-maven-plugin. That ought to be manageable I'd hope.

I didn't know about rewrite-recipe-bom. I think I just saw rewrite-spring using rewrite-bom and copied that. However, we also bring in rewrite-apache with its own version. I can replace that with your suggestion. Thanks!

[crankydillo]

I guess I'm as bad as most about skipping doc and looking for something to copy! :)

[timtebeek]

Hah, all good; sounds like we've reduced your versioning problems down to just two tags with the above discussion. It's at times hard to tell, especially with experienced users/contributors whether they are using everything as intended & documented, but glad to see we worked through and found something of use from it.