Merge remote-tracking branch 'origin' into directory-oracle

Author: sonalideshpandemsft

.changeset/angry-wings-battle.md

@@ -0,0 +1,89 @@
+---
+"@fluidframework/tree": minor
+"fluid-framework": minor
+"__section": tree
+---
+Schema snapshot compatibility checker
+
+This change adds alpha APIs for creating snapshots of view schema and testing their compatibility for the purposes
+of schema migrations.
+
+New APIs:
+
+- `checkCompatibility` - Checks the compatibility of the view schema which created the document against the view schema
+being used to open it.
+- `importCompatibilitySchemaSnapshot` - Parse a JSON representation of a tree schema into a concrete schema.
+- `exportCompatibilitySchemaSnapshot` - Returns a JSON representation of the tree schema for snapshot compatibility checking.
+
+#### Example: Current view schema vs. historical view schema
+
+An application author is developing an app that has a schema for storing 2D Points.
+They wish to maintain backwards compatibility in future versions and avoid changing their view schema in a way that breaks
+this behavior.
+When introducing a new initial schema, they persists a snapshot using `exportCompatibilitySchemaSnapshot`:
+
+```ts
+const factory = new SchemaFactory("test");
+
+// The past view schema, for the purposes of illustration. This wouldn't normally appear as a concrete schema in the test
+// checking compatibility, but rather would be loaded from a snapshot.
+class Point2D extends factory.object("Point", {
+	x: factory.number,
+	y: factory.number,
+}) {}
+const viewSchema = new TreeViewConfiguration({ schema: Point2D });
+const encodedSchema = JSON.stringify(exportCompatibilitySchemaSnapshot(viewSchema));
+fs.writeFileSync("PointSchema.json", encodedSchema);
+```
+
+Next they create a regression test to ensure that the current view schema can read content written by the original view
+schema (`SchemaCompatibilityStatus.canUpgrade`). Initially `currentViewSchema === Point2D`:
+
+```ts
+const encodedSchema = JSON.parse(fs.readFileSync("PointSchema.json", "utf8"));
+const oldViewSchema = importCompatibilitySchemaSnapshot(encodedSchema);
+
+// Check to see if the document created by the historical view schema can be opened with the current view schema
+const compatibilityStatus = checkCompatibility(oldViewSchema, currentViewSchema);
+
+// Check to see if the document created by the historical view schema can be opened with the current view schema
+const backwardsCompatibilityStatus = checkCompatibility(oldViewSchema, currentViewSchema);
+
+// z is not present in Point2D, so the schema must be upgraded
+assert.equal(backwardsCompatibilityStatus.canView, false);
+
+// The schema can be upgraded to add the new optional field
+assert.equal(backwardsCompatibilityStatus.canUpgrade, true);
+```
+
+Additionally, they a regression test to ensure that older view schemas can read content written by the current view
+schema (`SchemaCompatibilityStatus.canView`):
+
+```ts
+// Test what the old version of the application would do with a tree using the new schema:
+const forwardsCompatibilityStatus = checkCompatibility(currentViewSchema, oldViewSchema);
+
+// If the old schema set allowUnknownOptionalFields, this would be true, but since it did not,
+// this assert will fail, detecting the forwards compatibility break:
+// this means these two versions of the application cannot collaborate on content using these schema.
+assert.equal(forwardsCompatibilityStatus.canView, true);
+```
+
+Later in the application development cycle, the application author decides they want to change their Point2D to
+a Point3D, adding an extra field:
+
+```ts
+// Build the current view schema
+const schemaFactory = new SchemaFactory("test");
+class Point3D extends schemaFactory.object("Point", {
+	x: factory.number,
+	y: factory.number,
+
+	// The current schema has a new optional field that was not present on Point2D
+	z: factory.optional(factory.number),
+}) {}
+```
+
+The test first compatibility test will pass as the Point2D schema is upgradeable to a Point3D schema.
+However, the second compatibility test fill fail as an application using the Point2D view schema cannot collaborate on
+content authored using the Point3D schema.

.changeset/big-items-stop.md

@@ -20,7 +20,8 @@ jobs:
       pull-requests: write # for marocchino/sticky-pull-request-comment to create or update PR comment
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # ratchet:actions/checkout@v3
+      # release notes: https://github.com/actions/checkout/releases/tag/v5.0.0
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # ratchet:actions/checkout@v5
         with:
           persist-credentials: false
 

.changeset/metal-games-love.md

@@ -26,7 +26,8 @@ jobs:
     name: vale
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # ratchet:actions/checkout@v3
+      # release notes: https://github.com/actions/checkout/releases/tag/v5.0.0
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # ratchet:actions/checkout@v5
         with:
           persist-credentials: false
       - uses: errata-ai/vale-action@d89dee975228ae261d22c15adcd03578634d429c # ratchet:errata-ai/vale-action@v2.1.1

.changeset/sweet-groups-love.md

@@ -22,15 +22,19 @@ jobs:
     runs-on: ubuntu-latest
     if: contains(github.event.pull_request.labels.*.name, 'changeset-required')
     steps:
-      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # ratchet:actions/checkout@v3
+      # release notes: https://github.com/actions/checkout/releases/tag/v5.0.0
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # ratchet:actions/checkout@v5
         with:
           fetch-depth: "0" # all history
           persist-credentials: false
           ref: ${{ github.event.pull_request.head.sha }} # Check out the head commit, not the merge commit
 
       # install and configure node, pnpm and the changeset tools
-      - uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2 # ratchet:pnpm/action-setup@v4
-      - uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # ratchet:actions/setup-node@v3
+      # release notes: https://github.com/pnpm/action-setup/releases/tag/v4.2.0
+      - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # ratchet:pnpm/action-setup@v4
+
+      # release notes: https://github.com/actions/setup-node/releases/tag/v6.0.0
+      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # ratchet:actions/setup-node@v6
         with:
           node-version-file: .nvmrc
           cache: "pnpm"

.github/workflows/changeset-reporter.yml

@@ -21,7 +21,8 @@ jobs:
       pull-requests: write  # for marocchino/sticky-pull-request-comment to create or update PR comment
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # ratchet:actions/checkout@v4
+      # release notes: https://github.com/actions/checkout/releases/tag/v5.0.0
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # ratchet:actions/checkout@v5
         with:
           persist-credentials: false
           submodules: false

.github/workflows/pr-changeset-review.yml

@@ -19,7 +19,8 @@ jobs:
     name: Validate CODEOWNERS
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # ratchet:actions/checkout@v3
+      # release notes: https://github.com/actions/checkout/releases/tag/v5.0.0
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # ratchet:actions/checkout@v5
         with:
           persist-credentials: false
       - uses: mszostok/codeowners-validator@7f3f5e28c6d7b8dfae5731e54ce2272ca384592f # ratchet:mszostok/codeowners-validator@v0.7.4

.github/workflows/pr-check-changeset.yml

@@ -35,8 +35,11 @@ jobs:
           fetch-depth: "0" # all history, including tags
           persist-credentials: false
 
-      - uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2 # ratchet:pnpm/action-setup@v4
-      - uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # ratchet:actions/setup-node@v3
+      # release notes: https://github.com/pnpm/action-setup/releases/tag/v4.2.0
+      - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # ratchet:pnpm/action-setup@v4
+
+      # release notes: https://github.com/actions/setup-node/releases/tag/v6.0.0
+      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # ratchet:actions/setup-node@v6
         with:
           node-version-file: .nvmrc
           cache: "pnpm"