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.

Each exported API has exactly one release tag, unless it has the @legacy tag, which is always paired with @public or @alpha.

Important: there are other modifier tags used in exported APIs which are not "release tags" but which communicate important information to the consumer of the API. Some of these (for example @sealed and @system) express additional restrictions or expectations around how an API will be used and how it might change across versions. Please ensure you have examined and understand all the tags present on an API before using it.

@public

APIs tagged with @public are APIs that are suitable for general, production use. We guarantee full SemVer compliance for these APIs, unless they are also tagged with @sealed or @system, in which case there are additional restrictions around their use.

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 any explicit stability guarantees for @beta APIs. For this reason, they should not be used in production scenarios.

@alpha

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

Guidance

An API should generally be marked as @alpha when part of an experiment. It should be part of an agreed-upon plan including direct customer engagement to help evaluate the API in preparation for eventual promotion to @beta or removal.

Stability Guarantees

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

@legacy

@legacy is a custom tag for APIs that were in use during Fluid Framework v1.x and remain supported while use is migrated away. No additional features are expected to show up under @legacy.

There are two classes of legacy support: +@public and +@alpha

@legacy+@public

These APIs are stable with the same guarantees as regular @public.

@legacy+@alpha

We currently reserve the @legacy+@alpha tag combo 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.

@legacy+@beta

There is no use case for @legacy+@beta at this time and the combo should not be used.

Guidance

An API should generally only be marked as @legacy if it is referenced by an existing @legacy API (i.e. when api-extractor reports that you forgot to export 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 @legacy+@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 @legacy+@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.