JEP 12: Treatment of standard APIs supporting preview features

[Dan Smith]

> On Mar 5, 2018, at 5:27 PM, Alex Buckley <alex.buckley at oracle.com> wrote:
> 
> The decision to target the JEP as a preview language feature in JDK $N would have to consider the risk of removing the java.lang support in JDK $N+1 if the feature turns out to be a dud.

(And changes like modifying method signatures or renaming declarations amount to deleting the old one and adding a new one.)

> the silent compatibility risk is for code which used the java.lang changes "directly"

Yes, this describes my concern. Preview features that use libraries are significantly more risky than preview features that do not, because they're making permanent commitments in the form of APIs that users can refer to.

Impacts of that risk:
- Increases pressure to avoid shipping preview features that have an API component
- Decreases likelihood that substantive feedback will lead to changes in the feature
- Increases pressure to just live with a bad idea once it's in the wild

This leaves us with some distortions in the treatment of some features, and a risk of confusion. For example, somebody developing a preview feature may not take compatibility as seriously as they otherwise would in the initial release, only to discover later that they've made some unexpected commitments.

> But fundamentally we can deprecate-for-removal to push that code in the right direction.

If we're comfortable making liberal use of deprecation in the case of preview feature-related APIs, that's a reasonable way out. That might include adding notices to the javadoc: "This API is part of a preview feature. Use at your own risk."

If that's the consensus, maybe we could call this out in JEP 12 and in the deprecation policies? (Is there some document somewhere that describes deprecation policies?)

Are there any API changes that might be needed to support a preview feature that _wouldn't_ be easy to deprecate? New methods, classes, fields, enum constants are all straightforward. I'm wondering if there are other possible API changes that wouldn't work out so well?

—Dan