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.

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.

Virtual patches

In order to facilitate the transition to the expected developer workflows of version 1.0.0, FluidFramework adopted a virtual patch versioning scheme which combines the minor and patch components into the third version part. The beta versioning scheme where the first version part is 0 (e.g. 0.51.0) does not provide enough resolution to represent the three typical change types. Virtual patch versioning addresses this by representing minor (incremental) versions with 1000 increments to the third version part. Major versions are represented with the second version part, and patch versions continue to be represented with a 1 increment to the third version part. To avoid confusion with number of digits, a new major version starts with a third component of 1000 rather than 0, e.g. 0.58.1000.

Reactive versioning

FluidFramework is in the progress of transitioning to a reactive versioning system. Under this system, the developer that makes a change that would require a version change is also responsible for making that version change in that same PR. This contrasts with the old pre-bump system used by FluidFramework (where package versions are preemptively bumped following a release) and with other systems where a package version is set as part of the release process. There is automation (work in progress) to alert developers of the need to also bump a package version.

Releases

Every 2 weeks, a release branch is created from which packages are published to npmjs. Release branches may be for major or minor releases depending on the schedule, and patch releases may be made from either branch after the initial release on demand to address bugs or security issues.

Schedule and cadence

Before 1.0.0

Prior to the release of 1.0.0, major releases are expected every 4 weeks. This means each major release is also expected to have one additional minor release. Version 0.58.1000 is the first major version to follow this schedule, and 2 major releases are expected under this system before reaching 1.0.0. I.e. the releases expected before 1.0.0 are: 0.58.1000, 0.58.2000, 0.59.1000, and 0.59.2000.

1.0.0 and onward

With the release of 1.0.0 onward, major releases are initially expected every 6 weeks and minor releases will continue every 2 weeks when there isn't a major release. This means each major release is also expected to have two additional minor releases. As FluidFramework matures further, the major release cadence is expected to lengthen beyond 6 weeks. The minor release cadence is subject to change as well (though there are currently no existing plans).

Exception: "3P" packages

"3P" packages targeted primarily at external consumers (e.g. azure-client, fluidframework) will reach 1.0.0 on a separate timeline. Until that point they will also follow the virtual patch version system described above.