Release Tags

Release tags are TSDoc Modifier tags that can be used to explicitly denote the stability guarantees associated with an API and who should be using it. Each release tag has its own associated stability guarantees that dictate when and how breaking changes are permitted.

Note: at most one release tag may appear within a single TSDoc comment.

@public

APIs tagged with @public are APIs that are suitable for general, production use. We guarantee SemVer compliance for these APIs.

Guidance

APIs should be marked as @public when we believe they are stable and ready for production use. Modifications to public APIs are subject to SemVer compliance, meaning that breaking changes are only permitted in major releases.

• See Breaking vs Non-breaking Changes for more details about these stability guarantees.

Pull requests (PRs) adding or modifying existing public APIs, as well as PRs promoting APIs from another release tag to @public are subject to extra review scrutiny.

Stability Guarantees

We guarantee full SemVer compliance. Any deviation from this is a bug.

@beta

APIs tagged with @beta are APIs for which we are actively seeking feedback. Customers are encouraged to try it and provide feedback. However, a beta API should NOT be used in production, because it may be changed or removed in a future version.

Guidance

An API should generally only be marked as @beta as a part of an agreed-upon product plan including direct customer engagement to help evaluate the API in preparation for eventual promotion to @public.

Stability Guarantees

We do not make an explicit stability guarantees for @beta APIs. For this reason, they should not be used in production scenarios.

@alpha

We currently reserve the @alpha tag for APIs that are currently in use by known partners (with previous agreement), but which we do not plan to support long term. The intention over time is to further refine our public API surface and to help those partners migrate to it.

It is important to note that this is a deviation from typical meanings of alpha. As we migrate partners off of these APIs, we may eventually reclaim the @alpha tag for a more traditional meaning. But for now, this tag means something special to the Fluid Framework.

Guidance

An API should generally only be marked as @alpha if it is referenced by an existing @alpha API (i.e. when api-extractor reports that you need to add it), or as needed to otherwise fulfill our support commitment to our partners.

Stability Guarantees

The agreement we have come to with our internal (Microsoft) partners is that we reserve the right to make breaking changes to our @alpha APIs in minor releases, but not in patch releases. Our current release process has us shipping minor releases from regularly cut release branches, so breaking changes to @alpha APIs may be made directly on the main branch.

• Remember to always add a changeset when making breaking changes!

@internal

We reserve the @internal tag to denote APIs that are only intended for use within the Fluid Framework repository. In the future, we will begin omitting these APIs from our published packages altogether to ensure they are not visible to external consumers.

Guidance

APIs should be marked as @internal if they are not intended for external consumption but need to be shared between packages within the Fluid Framework repository.

When considering if an API should be surfaced as @internal consider the following:

• Does it really need to be exposed at all? Do multiple packages in our repo need access to it? If not, consider making the API private to only the package that needs it.

Stability Guarantees

We make no stability guarantees whatsoever for @internal API members.