Branches, Versions, and Releases

Development branches

FluidFramework maintains two active development branches: main and next. The two branches serve to segregate breaking and non-breaking changes where breaking changes must be exclusively be made in next while non-breaking changes may be made in either branch. main serves as the default branch, and developers should write features in a non-breaking way when possible.

main

Developers may only merge non-breaking changes into the main branch. This is enforced by way of automation where open PRs are checked for breaking changes (see also Breaking vs Non-breaking Changes (work in progress). Release branches are created from main for each major and minor release.

next

Breaking changes must always go into the next branch and must conform with version compatibility expectations. Non-breaking changes may also be made in this branch, though this should be reserved for changes that are not desired in the main branch.

lts

main and next are used to support our alpha/dev releases. On the other hand, lts branch in used to support our active (development) major release and its subsequent minor versions. For example, if 1.x is our current active major release, lts branch is used for any upcoming minor releases: 1.2.0, 1.3.0 etc.

Branch syncing

The main and next branches are synced regularly to ensure that developers are working with up-to-date versions of code. An automated process (work in progress) automatically merges commits made to main into next. Where a commit cannot be merged automatically, a PR is opened on the original commit author to resolve conflicts and complete the merge.

At the end of every major release cycle, next is merged into main and the major release branch is then created from main. Following this, development for the subsequent next version may begin in next.

Versions

FluidFramework packages conform to semantic versioning (semver) for versions 1.0.0 and later. Major versions are expected to be breaking, minor versions are expected to contain non-breaking incremental changes, and patch versions are expected to contain only bug fixes, security fixes, and other implementation-only changes. Versions prior to 1.0.0 follow a modified semver using virtual patch versioning.

Alpha/Dev Releases

Every 2 weeks, an alpha release branch is created from which packages are published to npmjs. The semantics of alpha releases is [major.minor.patch]-internal-*, and you will see them published on npmjs. [major.minor.patch] in this context indicate the next production release that will contain features published in the given alpha release.

As a general guideline:

• Alpha releases should not be used in production environment.
• Alpha features are not documented on ff.com.
• Alpha features likely contain APIs that may significantly change before next production release.

To facilitate more streamlined development cycle, we still try to distinguish between minor (coming from main branch) and major (coming from next branch) alpha releases - however all of them should still be considered alpha releases in terms of promises they are conveying.

Production/LTS Releases

Every (approximately) 12-18 months, Fluid Framework will release production release that is intended for general consumption.

In contrast to alpha releases:

• Production releases are intended for production environment.
• Features are documented on ff.com.
• Production releases are following strict semver and minor/major breaking rules.
• We offer long term support on any production release and 36 month retirement announcement.

Current LTS FF release is 1.x. The dates for 2.0 release have not been announced yet.