Add minDocumentRuntimeVersion compatibility API by WillieHabi · Pull Request #27656 · microsoft/FluidFramework

WillieHabi · 2026-07-08T19:36:05Z

Description

Adds minDocumentRuntimeVersion as the preferred name for configuring the minimum Fluid runtime version required to open or process documents created or loaded by a container runtime.

The existing minVersionForCollab parameter remains supported as a deprecated compatibility alias for now, with removal planned for 3.0.0 as part of #27180. Callers should specify only one of minDocumentRuntimeVersion or minVersionForCollab.

This also makes MinDocumentRuntimeVersion the preferred exported type for new API surfaces. Existing APIs that referenced MinimumVersionForCollab have been updated to reference MinDocumentRuntimeVersion. MinimumVersionForCollab remains supported as a deprecated alias.

Additional compatibility-related surfaces now use the preferred name where safe:

CodecWriteOptionsBeta now supports minDocumentRuntimeVersion and keeps minVersionForCollab as a deprecated compatibility alias.
Runtime/datastore context surfaces now expose minDocumentRuntimeVersion while keeping minVersionForCollab as a deprecated compatibility alias where needed.
Service client method parameter names now use minDocumentRuntimeVersion.

Persisted schema/wire-format fields intentionally remain named minVersionForCollab

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-07-08T19:37:01Z

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (1496 lines, 134 files), I've queued these reviewers:

Correctness — logic errors, race conditions, lifecycle issues
Security — vulnerabilities, secret exposure, injection
API Compatibility — breaking changes, release tags, type design
Performance — algorithmic regressions, memory leaks
Testing — coverage gaps, hollow tests

How this works

Adjust the reviewer set by ticking/unticking boxes above. Reviewer toggles alone don't trigger anything.
Tick Start review below to dispatch the review fleet.
After review finishes, tick Start review again to request another run — it auto-resets after each dispatch.
This comment updates as new commits land; your reviewer selections are preserved.
Start review

Copilot

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

jason-ha

No other internal uses of minVersionForCollab that need addressed?
Check with API counsel if this is the name. I was expecting to see minDocumentRuntimeVersion - I'm okay with minimum spelled out but I don't know what the recommendation is.

jason-ha · 2026-07-08T23:30:13Z

+	 *
+	 * @remarks Prefer {@link LoadContainerRuntimeParams.minimumDocumentRuntimeVersion} for new usages.


Also deprecated, right?

jason-ha · 2026-07-08T23:33:34Z

 ## Cross-client Compatibility Configuration and Enforcement

-### minVersionForCollab
+### minimumDocumentRuntimeVersion / minVersionForCollab


Can we just have the new name?
If entry with old name should stick around for tombstoning, then keep it on its own and refer back to here.

jason-ha · 2026-07-08T23:33:52Z

+ * @input
+ * @public
+ */
+export type MinimumDocumentRuntimeVersion = MinimumVersionForCollab;


This one should get the main definition and the other is deprecated alias, yeah?

jason-ha · 2026-07-08T23:35:56Z

+function getMinVersionForCollabFromParams(
+	minimumDocumentRuntimeVersion: MinimumDocumentRuntimeVersion | undefined,
+	minVersionForCollab: MinimumVersionForCollab | undefined,
+): MinimumVersionForCollab {
+	if (
+		minimumDocumentRuntimeVersion !== undefined &&
+		minVersionForCollab !== undefined &&
+		minimumDocumentRuntimeVersion !== minVersionForCollab
+	) {
+		throw new UsageError(
+			"minimumDocumentRuntimeVersion and minVersionForCollab must match when both are provided.",
+		);
+	}


Why do we need this?
Thinking that if we have some consistency check I would check that only one is defined.

jason-ha · 2026-07-08T23:38:04Z

+"__section": feature
+---
+
+Add document runtime version naming for compatibility configuration


We should be deprecating the old.
Look over the existing deprecation/breaking issues. Probably one of them can be updated and referred to here.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…time-version

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jason-ha

I've stopped reviewing part way. There seems like a lot of minVersionForCollab sticking around. Hard to see what the long-term code state will be.

jason-ha · 2026-07-09T19:12:08Z

 interface IFoo {
 	foo: string;
-	minVersionForCollab: MinimumVersionForCollab | undefined;
+	minVersionForCollab: MinDocumentRuntimeVersion | undefined;


I guess this minVersionForCollab is an arbitrary test property?
Maybe it could have a name that is neither minVersionForCollab nor minDocumentRuntimeVersion.

jason-ha · 2026-07-09T19:13:40Z

+	 * See {@link @fluidframework/container-runtime#LoadContainerRuntimeParams.minDocumentRuntimeVersion} for more details.
 	 */
-	readonly minVersionForCollab: MinimumVersionForCollab;
+	readonly minVersionForCollab: MinDocumentRuntimeVersion;


rename property?

jason-ha · 2026-07-09T19:16:21Z

@@ -179,7 +179,7 @@ export interface CodecVersionBase<
 	 * `undefined` should be used for unstable codec versions (with string FormatVersions),
 	 * as well as previously stabilized formats that are discontinued (meaning we always prefer to use some other format for encoding).
 	 */
-	readonly minVersionForCollab: MinimumVersionForCollab | undefined;
+	readonly minVersionForCollab: MinDocumentRuntimeVersion | undefined;


property rename?

jason-ha · 2026-07-09T19:17:43Z

 	 * the data's format should be versioned and if they can't handle the format they should error.
 	 */
-	readonly minVersionForCollab: MinimumVersionForCollab;
+	readonly minVersionForCollab: MinDocumentRuntimeVersion;


Can this be renamed? How would it need staged?

jason-ha · 2026-07-09T19:20:22Z

 export function extractPersistedSchema(
 	schema: ImplicitFieldSchema,
-	minVersionForCollab: MinimumVersionForCollab,
+	minVersionForCollab: MinDocumentRuntimeVersion,


jason-ha · 2026-07-09T19:23:36Z

@@ -24,7 +24,7 @@ import type { ITree } from "@fluidframework/tree";
 *
 * @deprecated Specify the minimum Fluid Framework version directly via the
 * `minVersionForCollab` parameter, which accepts a


Update to minDocumentRuntimeVersion

jason-ha · 2026-07-09T19:25:01Z

 							provideEntryPoint: mockProvideEntryPoint,
-							// @ts-expect-error - Invalid version strings are not castable to MinimumVersionForCollab
+							// @ts-expect-error - Invalid version strings are not castable to MinDocumentRuntimeVersion
 							minVersionForCollab: version,


This and many others above aren't renamed?

jason-ha · 2026-07-09T19:26:43Z

 	readonly isReadOnly: () => boolean;
-	readonly minVersionForCollab: MinimumVersionForCollab;
+	readonly minVersionForCollab: MinDocumentRuntimeVersion;
 }


Looks renamable.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-07-10T15:53:15Z

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-website@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-website@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  294296 links
    1937 destination URLs
    2187 URLs ignored
       0 warnings
       0 errors

github-actions · 2026-07-10T16:21:09Z

Bundle size comparison

Base commit: 006b9fcdfe1a7083da88f7b2faf010ec33cad26c
Head commit: 91d540f390d06201b23934f87f0b5efef1dcc679

Notable changes

🔴 azureClient.js: parsed 619098 → 619672 (+574), gzip 164826 → 164993 (+167)
🔴 odspClient.js: parsed 591824 → 592398 (+574), gzip 158912 → 159094 (+182)
🔴 aqueduct.js: parsed 525587 → 526140 (+553), gzip 140710 → 140852 (+142)
🔴 fluidFramework.js: parsed 392708 → 394420 (+1712), gzip 111481 → 111845 (+364)
🔴 sharedTree.js: parsed 382095 → 383800 (+1705), gzip 108869 → 109224 (+355)

Per-bundle deltas

`@fluid-example/bundle-size-tests`

🔴 azureClient.js: parsed 619098 → 619672 (+574), gzip 164826 → 164993 (+167)
🔴 odspClient.js: parsed 591824 → 592398 (+574), gzip 158912 → 159094 (+182)
🔴 aqueduct.js: parsed 525587 → 526140 (+553), gzip 140710 → 140852 (+142)
🔴 fluidFramework.js: parsed 392708 → 394420 (+1712), gzip 111481 → 111845 (+364)
🔴 sharedTree.js: parsed 382095 → 383800 (+1705), gzip 108869 → 109224 (+355)
containerRuntime.js: parsed 303937 → 304372 (+435), gzip 83213 → 83302 (+89)
sharedString.js: parsed 175984 → 175991 (+7), gzip 49445 → 49453 (+8)
experimentalSharedTree.js: parsed 160798 → 160798 (0), gzip 45804 → 45804 (0)
matrix.js: parsed 159845 → 159852 (+7), gzip 45411 → 45418 (+7)
loader.js: parsed 145256 → 145270 (+14), gzip 39063 → 39077 (+14)
odspDriver.js: parsed 104329 → 104350 (+21), gzip 32646 → 32635 (-11)
directory.js: parsed 66616 → 66623 (+7), gzip 18532 → 18540 (+8)
748.js: parsed 58793 → 58793 (0), gzip 17827 → 17827 (0)
map.js: parsed 46709 → 46716 (+7), gzip 14310 → 14318 (+8)
odspPrefetchSnapshot.js: parsed 45642 → 45656 (+14), gzip 15277 → 15285 (+8)
985.js: parsed 44491 → 44491 (0), gzip 13726 → 13726 (0)
summarizerDelayLoadedModule.js: parsed 30749 → 30749 (0), gzip 7753 → 7753 (0)
socketModule.js: parsed 26476 → 26483 (+7), gzip 7885 → 7895 (+10)
createNewModule.js: parsed 12480 → 12480 (0), gzip 4786 → 4786 (0)
summaryModule.js: parsed 3797 → 3797 (0), gzip 1860 → 1860 (0)
connectionState.js: parsed 724 → 724 (0), gzip 429 → 429 (0)
sharedTreeAttributes.js: parsed 666 → 673 (+7), gzip 432 → 442 (+10)
debugAssert.js: parsed 429 → 429 (0), gzip 299 → 299 (0)
FluidFramework-HashFallback.js: parsed 422 → 422 (0), gzip 316 → 316 (0)

Add minimumDocumentRuntimeVersion compatibility alias

ebe9f4d

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

WillieHabi marked this pull request as ready for review July 8, 2026 20:18

WillieHabi requested review from a team as code owners July 8, 2026 20:18

Copilot AI review requested due to automatic review settings July 8, 2026 20:18

Copilot started reviewing on behalf of WillieHabi July 8, 2026 20:18 View session

Copilot AI reviewed Jul 8, 2026

View reviewed changes

WillieHabi requested review from jason-ha and scottn12 July 8, 2026 23:01

jason-ha reviewed Jul 8, 2026

View reviewed changes

Use minDocumentRuntimeVersion API name

a46d718

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

WillieHabi requested a review from a team as a code owner July 9, 2026 15:48

WillieHabi and others added 3 commits July 9, 2026 09:01

Merge remote-tracking branch 'upstream/main' into wh/min-document-run…

e2bcc03

…time-version

Clean tree API report output

3d8a6fa

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fix API naming CI failures

8393687

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

WillieHabi changed the title ~~Add minimumDocumentRuntimeVersion compatibility alias~~ Add minDocumentRuntimeVersion compatibility API Jul 9, 2026

WillieHabi and others added 2 commits July 9, 2026 10:35

Fix fluid-framework legacy API report

344a1f1

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove issue link from deprecated API TSDoc

e30f854

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jason-ha reviewed Jul 9, 2026

View reviewed changes

WillieHabi and others added 5 commits July 9, 2026 13:31

Expand minDocumentRuntimeVersion rename pass

c33d03e

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Clean remaining minVersionForCollab docs examples

c032967

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Clean MinimumVersionForCollab docs references

cbcfc52

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fix tree tests for minDocumentRuntimeVersion rename

3fa188f

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fix Datastore capitalization in changeset

91d540f

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

		*
		* @remarks Prefer {@link LoadContainerRuntimeParams.minimumDocumentRuntimeVersion} for new usages.

Uh oh!

Conversation

WillieHabi commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

github-actions Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

jason-ha left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jason-ha left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 10, 2026

linkcheck output

Uh oh!

github-actions Bot commented Jul 10, 2026

Bundle size comparison

Notable changes

@fluid-example/bundle-size-tests

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

WillieHabi commented Jul 8, 2026 •

edited

Loading

github-actions Bot commented Jul 8, 2026 •

edited

Loading

`@fluid-example/bundle-size-tests`