Cross‐Client Compatibility

Introduction

Cross-client compatibility ensures users on different Fluid Framework versions can collaborate safely. It protects against data corruption and runtime errors, giving customers the confidence to upgrade at their own pace. For developers, it provides a clear, structured path to ship new features without breaking existing experiences. This document outlines the information FF engineers need to know about the new cross-client compatibility policy. It overviews the cross-client compatibility policy and explains how to:

• Identify cross-client compatibility breaking changes
• Enforce the policy
• Safely stage breaking changes
• Test for cross-client compatibility

Terminology: This document uses the terms N, N-1 and N-2 to refer to Fluid Framework public major release versions, and the acronym FF for Fluid Framework.

Policy Overview

In short, the cross-client compatibility policy states that any two adjacent public major releases of FF (N/N-1) are fully compatible by default where N-1 is the latest minor release of that major version series. In addition, public major releases which are next to adjacent (N/N-2) are not compatible by default but can be made fully compatible via proper configuration.

For example, two sessions running 1.x and 2.x are fully compatible. This means we guarantee their compatibility with each other via following correct development practices, testing and enforcement. The customer will not need to take any additional action to ensure their compatibility. Furthermore, two sessions running 1.x and 3.x are not fully compatible by default but can be made to be fully compatible with the proper configurations. Lastly, two sessions running 1.x and 4.x are considered incompatible and we do not support collaboration between these sessions. Please note: In the above scenario, 1.x must refer to the latest minor release of the 1.0.0 series. For instance, at the time this document was written 1.4.0 is the latest minor release of the 1.0.0 series. Assuming this remains true, 1.4.0 is compatible with 2.x clients, but a lower version such as 1.3.7 would not be considered compatible by default.

Note: This policy applies only to runtime-level features.

Identifying Cross-Client Compatibility Breaking Changes

When evaluating if a change is cross-client compatible, consider the relationship between code and data. Each client must be able to interpret the data it receives. If not, this could lead to data corruption or runtime errors. The following are examples of changes that could change the data format:

• Introducing a new op type.
• Changing the format of an op (i.e. adding or removing a field).
• Changing the format of summaries.
• Changing the data schema format (i.e. SharedTree). However, there are many other types of changes that could impact cross-client compatibility.

Cross-client Compatibility Enforcement

If a change was identified to affect the data format (see above section), then it should be gated by a container runtime option. Runtime options are then enforced via the minVersionForCollab property to ensure customers do not accidentally break older clients by enabling cross-client compatibility breaking features prematurely. minVersionForCollab defines the minimum FF runtime version that is required for collaboration on a document. Customers are encouraged to set minVersionForCollab to the highest version their users are saturated on. If the customer does not set minVersionForCollab, a default value will be assigned. minVersionForCollab controls the "default configurations" and "unsafe configuration prevention" mechanisms explained below.

Default Configurations

The runtime uses minVersionForCollab to automatically set certain container runtime options based on the value of minVersionForCollab. For example, if minVersionForCollab is set to "2.0.0", then we can safely enable features such as grouped batching, since the lowest version we need to support collaboration with will understand the data format changes associated with grouped batching. On the other hand, features such as createBlobPayloadPending will be disabled, as clients need to be running runtime version 2.40.0 or later to understand the data format changes associated with that feature.

Unsafe Configuration Prevention

If a client tries to enable a runtime option that requires a version higher than the document's minVersionForCollab, then the runtime will fail to instantiate and throw an error. For example, let's say the container author set minVersionForCollab to "1.4.0" and enabledGroupedBatching to true. In this case, the runtime would fail immediately stating that minVersionForCollab must be updated, since clients running the runtime version 1.4.0 cannot understand the data format of grouped batching being enabled.

Safely Staging Cross-Client Compatibility Breaking Changes

The following are the steps to safely stage changes that break cross-client compatibility.

1. Evaluate if a change breaks our cross-client compatibility policy

With the information from the previous section in mind, determine whether a change breaks our compatibility promises. Specifically, assess whether the data format has changed and whether older clients (within the defined compatibility window) have the necessary code to interpret the new format. If any clients within the collaboration window cannot interpret the new data format, proceed with the next steps. Additionally, developers should try to test their changes using our e2e test infrastructure to see if it breaks our cross-client compatibility tests (see testing section below).

2. Add a container runtime option to enable/disable the change

Add a mechanism to enable/disable your change by following these steps:

1. Add a container runtime option for your change. The option should control whether your change is enabled/disabled. For example, there exists a runtime option for createBlobPayloadPending which determines the using the new or legacy behavior.
2. Add a property corresponding to the container runtime option to IDocumentSchemaFeatures.
3. Update documentSchemaSupportedConfigs to include the property added in step (2). It should be instantiated as one of the IProperty classes (i.e. TrueOrUndefinedUpdate. Although unlikely, it's possible you may need to define a new class.
4. Update desiredSchema.runtime definition to include your new property. Follow existing patterns for reference.
5. Ensure the container runtime option is passed into the DocumentSchemaController constructor when instantiating a new container runtime. Follow the existing patterns for reference.

3. Edit the "Configuration Maps" for this change

In packages/runtime/container-runtime/src/compatUtils.ts, there are two configuration maps that must include an entry for each new runtime option. If an entry is missing, the build will fail to compile. This requirement ensures that all new runtime options are evaluated for their cross-client compatibility impact. For options that do not affect the data format, they should be explicitly omitted from RuntimeOptionsAffectingDocSchema (see the code comments for guidance).

The first map, runtimeOptionsAffectingDocSchemaConfigMap, which handles the "Default Configurations" mentioned above. Configure the entry corresponding to your runtime option as per the comments in the code.

The second map, runtimeOptionsAffectingDocSchemaConfigValidationMap which handles "Unsafe Configuration Prevention" as mentioned above as well. Configure the entry corresponding to your runtime option as per the comments in the code.

The exact implementation of these configuration maps may change in the future. Please refer to the code comments for additional guidance as they should be the latest source of truth.

4. File an ADO item to remove the container runtime option

Since our policy's maximum compatibility promise is N/N-2, we will eventually not require a mechanism to disable certain features. We may never want to enable certain features by default (i.e. enableRuntimeIdCompressor). In those cases, we will keep the enable/disable mechanism indefinitely. However, other features (i.e. enableGroupedBatching) are intended to eventually be a non-optional part of FF. If your change is the latter, then you should file an ADO item to eventually remove the container runtime option and enable/disable mechanism entirely. This should be an ADO item because:

1. It will likely be years before our policy allows us to remove the mechanism.
2. There is not currently a strong process/timeline for when we will be ready to do this. More information will be added in the future when appropriate.

Testing

FF's end-to-end test suite automatically generates cross-client compatibility variations using describeCompat() with "FullCompat". The variations will test cross-client compatibility scenarios by using one version of the FF runtime for creating containers and a different version for loading containers. For example, an example test may generate the following variations for cross-client compatibility scenarios:

compat cross-client - create with 2.43.0 (N) + load with 2.33.2 (N-1 fast train)
  ✔ Example test
compat cross-client - create with 2.43.0 (N) + load with 2.23.0 (N-2 fast train)
  ✔ Example test
compat cross-client - create with 2.43.0 (N) + load with 1.4.0 (N-1 slow train/LTS)
  ✔ Example test
compat cross-client - create with 2.33.2 (N-1 fast train) + load with 2.43.0 (N)
  ✔ Example test
compat cross-client - create with 2.23.0 (N-2 fast train) + load with 2.43.0 (N)
  ✔ Example test
compat cross-client - create with 1.4.0 (N-1 slow train/LTS) + load with 2.43.0 (N)
  ✔ Example test

To ensure your change is tested properly, write tests with multiple clients. If necessary, you can pass minVersionForCollab and container runtime options in ITestContainerConfig as needed.