Extensions API exports must be @public, remove @preview release tag

[ben-polinsky]

trafficstars

When extensions were first developed, it was thought that using the @beta jsdoc tag to represent an early-release API would be confusing, as the core library had many other APIs in beta at the time: the @preview tag was designated for extension-only preview APIs.

The @preview tag isn't necessary, though, since we already require the @extension tag to determine which APIs are available in extensions.

Let's use @beta from here on out for early-release/preview extension APIs.

We'll need to make changes to both the eslint-plugin and core.

[calebmshafer]

I didn't remember why we introduced preview when we discussed this internally but I did some digging and remember now.

We introduced preview flag to allowing us to slowly introduce APIs that are marked public, in our regular API, and not be fully committed to keeping them there in the Extension API. This gives us more flexibility to test out the new APIs, and ensure we're comfortable with the side effects they potentially have, before we commit to them in the long term.

One reason for the slow roll out is the Extension API needs to be more stable than our current public API due to the impact it has on consumers. Today, a breaking change is a build time failure but a breaking changing to our Extension API is a runtime failure (which is a lot worse). With that said, we do not have any additional or longer support policy in place today but I do expect we will at some point specifically to the Extension API.

Instead of removing the tag, I would suggest we clarify the reasoning and why we have it in the release tags guidelines to get rid of the confusion that had been raised.

Since we do not have a support policy today explicitly for the Extension API, we will fallback on the existing support policy for public APIs. In addition, we need to ensure that only @public APIs ever make it into the Extension API and no other APIs are allowed.

[ben-polinsky]

Alright that makes sense to me. I think there are only a couple @extension exports which are currently beta? Unless my regex failed me :) But we'll want to make sure they're ready for primetime if we're not allowing non-public tags to be extensions.

Looking toward the future: Do we obey semantic versioning for pushing a new version of an extension to applications remotely? Or do we always update no matter what?