New Issue: Improve support for new features that are unstable in 2.0 and stable in preview edition

Notifications Issues
1

28923, "bradcray", "Improve support for new features that are unstable in 2.0 and stable in preview edition", "2026-06-03T20:07:02Z"

In this issue, I'm wondering whether there's something we could do to improve the situation for developers and users when defining a language feature in both the preview and 2.0 editions. I'm thinking we could do something to both improve redundancy in the implementation while also improving the documentation for users.

At present, our best practice is to define two copies of the procedure, as follows:

@edition(first="preview")
proc foo() { ... }

@edition(last="2.0")
@unstable("…")
proc foo() { … }

This results in some amount of code duplication, particularly if foo() supports multiple overloads, as in a new operator or new Math procedure.

For the user, this shows up as two procedures in the documentation, one of which is marked with:

foo is available in the preview edition and is expected to be available in the next new edition.

The other with both:

foo was removed after the 2.0 edition. It is not available in editions after the 2.0 edition.

and

‘foo’ is unstable and may change in future.

This can be seen in cases like Bytes.contains and in lcm() being added in #28005.

As an alternative, perhaps we could support something like the following:

@edition(stabilizedIn="preview")
proc foo() { … }

to only have the routine defined once, and then to have it generate unstable warnings for editions prior to 'preview', and to generate documentation that would say something like: