Add `@IncubatingNextRelease` that is automatically replaced with `@Incubating(since="...")` when release is cut

[JLLeitschuh]

What problem are you trying to solve?

For those of us contributing outside of the governance of OpenRewrite, we don't know what version will be published next. If we want to add the @Incubating API to our API's we need to know what version will be published next.

Describe the solution you'd like

It would be lovely, if we could just annotate our incubating with @IncubatingNextRelease and the release process would go through the work of automatically replacing this with the correct number when the release is about to be cut.

Have you considered any alternatives or workarounds?

Alternatively, it would be nice if the README.md or the CONTRIBUTING.md kept some indication of what the next release number will be so we can specify it correctly.

Are you interested in [contributing this feature to OpenRewrite]

Not at this time, but I'd love to use this feature across both rewrite-analysis and rewrite-java-security

[knutwannheden]

I know what you mean. The status quo indeed doesn't feel very satisfactory. But modifying the sources during the release process also doesn't feel right to me.

Can we instead handle this at the process level? E.g. set a corresponding milestone on the PR? Of course there would still be the chance of divergence, but IMHO it isn't very bad either. We basically never remove these annotations either and we also make API breaking changes to API which doesn't have them (typically not to core API, however).

[JLLeitschuh]

Regarding your process, the replacement process doesn't need to occur during the release job itself. It could be a pre-release task you then push to the main branch, then cut a release from that change.

[knutwannheden]

Yes, that could be an option.

[timtebeek]

As a bit of context: We've since standardized our releases such that we cut minor releases whenever there are code changes, and patch releases whenever only the dependencies have changed. Major releases are rare to the point that I don't think we need to accommodate those. That makes me think we can just always use the likely next release number, given our every-two-weeks-release-cadence, such that I feel we wouldn't need anything more here. Would you all agree we can close this issue with that standardization?

[JLLeitschuh]

Is this versioning schema publicly documented anywhere?

It looks like the @Incubating annotation isn't documented anywhere in the docs: https://docs.openrewrite.org/authoring-recipes/recipe-conventions-and-best-practices?q=Incubating

[timtebeek]

For now the annotation is only documented in the attached JavaDoc: https://github.com/openrewrite/rewrite/blob/6db920138269f38cbfa052d6994598dacfe5b75e/rewrite-core/src/main/java/org/openrewrite/Incubating.java#L22-L29

The release strategy for now is not documented beyond what's listed above; it's partially automated, which we might automate further and then document when we find time.

[timtebeek]

Clearing out a couple items on the backlog; let's for now continue with the minorVersion++ in the existing @Incubation(since="...") annotation approach outlined above, since we'd need to wire up quite a few things to get the proposal here to work.