Introduce concept of Preview Features as a feature stabilization period

[WojciechMazur]

Currently Scala 3 has a concept of Experimental Feature - a feature that is introduced to standard library / language syntax but is prone to changes, might be unstable, break binary compatibility or be even removed in the future.
Currently our process does not describe well the stabilization period of currently experimental features. Both instability and lack of proper information might discourage users from trying out the new features which might reduce amount of feedback and can lead to lead maintaining flowed designs.

During the last Scala Core team meeting it was proposed to introduce a Preview Features as a interim stage between experimental and stable features. These might be treated as an early access to fully implemented, but not yet fully stabilized features that might introduce minor changes.

Stage	Name	Description	Usage
Stage 0	Early experimental / PoC	Feature is implemented behind a flag, awaits approval from SIP committee Highly prone to changes. Might be removed or redesigned at any moment	Requires explicit -experimental + -experimental.feature flags. Might requiring building compiler from a separate branch before usage.
Stage 1	Experimental	Feature has been accepted by the SIP committee but is still under active development. No source/binary guarantees. Might change, be removed or redesigned based on feedback from users. Not recommended to be used on daily usage by users, but encouraged to try out	Requires explicit -experimental + -experimental.feature flags
Stage 2	Preview	Feature has been fully implemented and would become stable after evaluation period. It is not going to be removed at any later point. Does not guarantee binary compatibility, but it is unlikely to introduce breaking changes. It can be adopted (in limited scope) to the needs of the users based on feedback gathered during evaluation period. It can be used by users that don't require binary compatibility e.g. applications but not libraries.	Enabled using --preview flag (optionally also --preview.feature flag)
Stage 3	Stable	Feature has been proven to not change during evaluation period. It becomes a stable feature and does guarantee source/binary compatibity in all the future versions	Enabled by default

All of the implemented features should follow the staging through experimental -> preview -> stable staging. Advancement between the 2 stages should happen in the first release of next minor release of Scala.

The compiler should track usage of preview features using mechanism similar to the one used by experimental features. It might be considered to either enable preview features selectively or to allow usage of all preview features when compiling under --preview mode.

[tarsa]

#22037 (comment)

I am not sure what to do here. Java has previews, would that help?

Java previews probably don't apply to Scala development process well. The Java previews (and incubator and experimental features) are controlled not only on compile time, but also on run time. All preview features are enabled using single switch --enable-preview, both on compile time and run time. Incubator features are enabled individually on run-time using switches like --add-modules jdk.incubator.vector or --add-modules jdk.incubator.concurrent (i.e. they are contained in Project Jigsaw / JPMS modules). Preview features are allowed to be somewhat tighly integrated with rest of codebase, since preview features are expected to be near final state (but sometimes they aren't, like: JEP 465: String Templates (Third Preview)). Incubator features reside in their own incubator module under parent package for all incubating features (jdk.incubator) and when exiting incubation they change their module name and package names. Incubator features are designed to be loosely coupled to rest of codebase, so they can be easily removed and they don't slow down regular development of non-incubator features.

Scala doesn't control the run time class loading, so it can't produce same errors as Java preview or incubator features. Scala could emulate some of the controlling functionality, by checking for flags enablement in static class initializers and conditionally throwing an exception.

P.S. I'm writing from memory and haven't spent a lot of time for fact-checking myself, but there shouldn't be significant inaccuracies.

Note that the preview periods in Java are sometimes extended without any user-facing change in meantime, e.g.
https://openjdk.org/jeps/499

JEP 499: Structured Concurrency (Fourth Preview)
(...)
We here propose to re-preview the API once more in JDK 24, without change, to give more time for feedback from real world usage.

[keynmol]

This would be a very welcome change!

I hope it can be accompanied by a living documentation page with a table like this:

	Implementation	Experimental	Preview	Stable
CanThrow capabilities	3.0.0	3.1.0	N/A	N/A
Erased definitions
Named Type Arguments
Numeric literals
Capture Checking
Tupled Function
Main Annotation
Safe initialization			3.3.4
Named tuples	3.5.2	3.6.1	3.6.2	3.7.0?

for all the experimental features to provide minimal versions where it's available/stabilised. Not necessarily a commitment, but a good view of where the language is at.

I struggle to fill the rest of the table as I have no idea where to get information on any of the cells in it.

I also added safe initialisation as it is not exposed as experimental feature, but the documentation marks it as experimental.