Fluid Releases and API Support Levels

Fluid Release Versions

Fluid Releases will be done through three channels

• Production
• Pre-release
• Dev release

Production Channel

Prod releases are our most stable releases, follow semver and are ready to be used in Production scenarios. These releases correspond to the latest tag on npm. This should be the channel used to get the most stable version of Fluid. Following semver (X.Y.Z), this channel will includes:

• Major releases (X) - Used when releasing breaking changes. Breaking changes can include API changes, runtime behavior changes and document format changes. Variable release cadence.
• Minor releases (Y) - Used when adding new features or non-critical bug fixes, released ~weekly.
• Patch releases (Z) - Used when releasing fixes for critical, time-sensitive bugs. Variable release cadence.

Pre-Release Channel (Release Candidates)

Pre-releases are for developers who want to try out early versions of upcoming Fluid releases and provide input as the Major release begins to take shape. There are no support guarantees for any new or existing APIs and Fluid documents generated by these releases and we recommend not using them in production as they could corrupt pre-existing documents when opened. However, these are great releases to try out new APIs or test your app with the upcoming release to speed up development. Since pre-releases precede a major release, we can also introduce any breaking changes including API, runtime behavior and document format changes in any RC all the way up to the GA release. For example, Fluid containers generated by RC1 are not guaranteed to be compatible with RC3 or the next GA. Pre-releases will be represented by the rc tags in npm. RCs are done with variable timing and go through our full battery of automated tests and always lead up to a major production release. We will designate some RCs to be Beta releases when they contain major features that make significant strides towards a Prod release. RCs close to a Prod release will be designated a Preview release. There are no guarantees for API breakages or Fluid document compatibility among the release changes. Assume you will have to throw away containers generated by release candidates.

Dev Release Channel

These are done on demand to preview new APIs or try fixes for our partners. They are represented by the dev tag in npm There are no guarantees for API breakages or Fluid document compatibility among the release changes. Assume you will have to throw away containers generated by older release candidates

API Support Levels

For packages that are part of the @fluidframework scope and the fluid-framework package, we use import paths to communicate the stability and guarantees associated with those APIs.

• Public APIs - These APIs are officially supported and any breaking changes to these APIs will be done in a major release and go through a deprecation phase before being removed.

• Beta APIs (/beta import path) - These APIs are on the path to being officially supported but can still change before becoming a Public API in a future release. They are meant as a preview for developers to experiment with and provide feedback. These APIs can be changed in minor releases. Production usage of these APIs is discouraged.

  • For JavaScript users, such APIs can be identified via the @beta tag included in their documentation.

• Alpha APIs (/alpha import path) - These APIs are unstable. They may become officially supported or removed. They will very likely change in a future release. They are meant as a preview for developers to experiment with and provide feedback. These APIs can be changed in minor releases. These APIs should not be used in production. Usage of some of these APIs may result in changes to persisted data. If the feature is later changed or removed, containers which used the feature may appear corrupted and be unrecoverable.

  • For JavaScript users, such APIs can be identified via the @alpha tag included in their documentation.

• Legacy APIs (/legacy import path) - These APIs were used by the early adopters of Fluid Framework, and we strongly discourage new applications from using these APIs. We will continue to support use of SharedMap & SharedDirectory DDSes until we provide a migration path to SharedTree in a future release.

  • For existing users of these Legacy APIs, you will have to use the /legacy import path. This is intentional to highlight that we do not encourage new development using these APIs and plan to provide a graceful path away from them in future.

  • For example, SharedMap is now a Legacy API and should be imported as follows:

    import { SharedMap } from "fluid-framework/legacy";

  • For JavaScript users, such APIs can be identified via the @legacy tag included in their documentation.

• System APIs - These APIs are reserved for internal system use and are not meant to be used directly. These may change at any time without notice. For cases in which such a type must be referenced, the contents should never be inspected.

  • For JavaScript users, such APIs can be identified via the @system tag included in their documentation.

• Internal APIs - These APIs are strictly for internal system use and should not be used. These may change at any time without notice.

  • Do not import any APIs from the /internal import path.
  • For JavaScript users, such APIs can be identified via the @internal tag included in their documentation. Such APIs should not be used.

There are no API stability guarantees for packages in the @fluid-experimental and @fluid-internal scopes. @fluid-experimental APIs are for developers to try experimental features and provide feedback. It's possible that these APIs can get completely scrapped or drastically changed in a minor release based on developer feedback. @fluid-internal APIs are only meant for internal consumption by the framework and should not be used.

For additional information on Release tags, visit the github documentation.