Fluid Releases and API Tags

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 Tags

There are no API guarantees for packages in the @fluid-experimental and @fluid-internal namespaces. @fluid-experimental APIs are for you to try and provide feedback on and @fluid-internal APIs are only meant for internal consumption by the framework and should not be used. For packages that are part of the @fluidframework namespace, we use API tagging to communicate the stability and guarantees associated with those APIs.

  • Public APIs (@public) - These are officially released and supported by us. Any breaking changes to these APIs will first be deprecated before being removed in a major release. We guarantee not to break them in minor and patch releases (respecting the semver guarantees)
  • Beta APIs (@beta) - These APIs are on the path to being officially supported but can still change in form before becoming a Public API. They are meant as a preview, for developers to experiment with and provide feedback. These APIs can change even in minor releases. As a result, prod use is discouraged.
  • Legacy APIs (@legacy) - These are early Fluid APIs used by early adopters of Fluid Framework. They are on a path to deprecation in a future release and we strongly encourage all new applications to avoid these APIs. Existing users of SharedMap DDS will need to use the legacy API until we provide a migration path to SharedTree in a future release.
  • Internal APIs (@internal) - Internal Fluid APIs, should not be used by applications.