From a58b992c0c64b9d12cf62cec41f39d3e1a8f2373 Mon Sep 17 00:00:00 2001 From: Tyler Butler Date: Fri, 19 Jul 2024 12:54:53 -0700 Subject: [PATCH] docs(client): Update changesets and generate release notes (#21897) The release notes were generated using the command in https://github.com/microsoft/FluidFramework/pull/21951 including the minor metadata additions to the source changesets. --------- Co-authored-by: Alex Villarreal <716334+alexvy86@users.noreply.github.com> Co-authored-by: Craig Macomber (Microsoft) <42876482+CraigMacomber@users.noreply.github.com> Co-authored-by: jzaffiro <110866475+jzaffiro@users.noreply.github.com> --- .changeset/blood-moon-rising.md | 4 +- .changeset/every-walls-grow.md | 2 +- .changeset/fresh-corridors-curtsy.md | 15 ++- .changeset/gold-badgers-float.md | 10 +- .changeset/great-papayas-jog.md | 11 +- .changeset/khaki-hairs-vanish.md | 15 ++- .changeset/silly-planets-wait.md | 2 +- .changeset/stale-rooms-bow.md | 5 +- .changeset/terrific-apples-run.md | 8 +- RELEASE_NOTES/2.1.0.md | 144 +++++++++++++++++++++++++++ 10 files changed, 198 insertions(+), 18 deletions(-) create mode 100644 RELEASE_NOTES/2.1.0.md diff --git a/.changeset/blood-moon-rising.md b/.changeset/blood-moon-rising.md index b4d15e0934b..1e1c26818ac 100644 --- a/.changeset/blood-moon-rising.md +++ b/.changeset/blood-moon-rising.md @@ -4,4 +4,6 @@ Updated `joi` dependency to latest major version -The `joi` dependency was updated from 14.3.1 to 17.3.1 to address a critical vulnerability exploit [CVE-2020-36604](https://github.com/advisories/GHSA-c429-5p7v-vgjp). This required updating the use of `joi` schema validation function within `property-query` to the new major version syntax. +The `joi` dependency was updated from 14.3.1 to 17.3.1 to address a critical vulnerability exploit +[CVE-2020-36604](https://github.com/advisories/GHSA-c429-5p7v-vgjp). This required updating the use of `joi` schema +validation function within property-query to the new major version syntax. diff --git a/.changeset/every-walls-grow.md b/.changeset/every-walls-grow.md index ac2929f4f26..82266c24c0d 100644 --- a/.changeset/every-walls-grow.md +++ b/.changeset/every-walls-grow.md @@ -5,4 +5,4 @@ Detect arrayNode iterator invalidation -This change updates the behavior of array nodes such that when we concurrently edit the array during iteration, it will throw an error. +When `arrayNode`s are edited concurrently during iteration, an error will be thrown. diff --git a/.changeset/fresh-corridors-curtsy.md b/.changeset/fresh-corridors-curtsy.md index ace3d09e8ac..250a2512844 100644 --- a/.changeset/fresh-corridors-curtsy.md +++ b/.changeset/fresh-corridors-curtsy.md @@ -2,6 +2,17 @@ "@fluidframework/tinylicious-client": minor --- -Promote Tinylicious Client APIs from `@beta` to `@public` +tinylicious-client: Promote APIs from beta to public -The Tinylicious Client is used in public examples and documentation, and therefore requires public level support. +Some tinylicious-client APIs were marked beta in previous releases. These APIs are now correctly marked public and also +sealed to indicate they are not to be implemented externally to Fluid Framework and not changed. + +Updated APIs: + +- [ITinyliciousAudience](https://fluidframework.com/docs/api/v2/tinylicious-client/itinyliciousaudience-typealias) sealed +- [TinyliciousClient](https://fluidframework.com/docs/api/v2/tinylicious-client/tinyliciousclient-class) sealed +- [TinyliciousClientProps](https://fluidframework.com/docs/api/v2/tinylicious-client/tinyliciousclientprops-interface) sealed +- [TinyliciousConnectionConfig](https://fluidframework.com/docs/api/v2/tinylicious-client/tinyliciousconnectionconfig-interface) sealed +- [TinyliciousContainerServices](https://fluidframework.com/docs/api/v2/tinylicious-client/tinyliciouscontainerservices-interface) sealed +- [TinyliciousMember](https://fluidframework.com/docs/api/v2/tinylicious-client/tinyliciousmember-interface) sealed +- [TinyliciousUser](https://fluidframework.com/docs/api/v2/tinylicious-client/tinylicioususer-interface) sealed diff --git a/.changeset/gold-badgers-float.md b/.changeset/gold-badgers-float.md index c7062f38abd..402e21bfe54 100644 --- a/.changeset/gold-badgers-float.md +++ b/.changeset/gold-badgers-float.md @@ -2,21 +2,23 @@ "@fluidframework/shared-object-base": minor --- -Added typeguard for SharedObjectKinds +Type guards for DDS types In the 2.0 release of Fluid, the concrete class implementations for DDSes were hidden from Fluid's API surface. This made `instanceof` checks fail to work correctly. There were ways to work around this in application code, but they involved boilerplate which required more understanding of Fluid internals than should be necessary. -This change adds a drop-in replacement to `instanceof`: the `.is()` method to `SharedObjectKind`. + +There is now a drop-in replacement to `instanceof`: the static `.is()` method to `SharedObjectKind`, which is available +on all DDSes. For example: ```typescript -// Works in FluidFramework 1.0 but not in the initial release of FluidFramework 2.0: +// Works in Fluid Framework 1.0 but not in the initial release of Fluid Framework 2.0: if (myObject instanceof SharedString) { // do something } -// With this change, that code can now be written like so: +// In Fluid Framework 2.0 and beyond, that code can now be written like so: if (SharedString.is(myObject)) { // do something } diff --git a/.changeset/great-papayas-jog.md b/.changeset/great-papayas-jog.md index 918413d073c..b202e2ae7db 100644 --- a/.changeset/great-papayas-jog.md +++ b/.changeset/great-papayas-jog.md @@ -2,6 +2,13 @@ "@fluidframework/merge-tree": minor --- -The expected type of the argument to the fromJSONObject function has changed. +The Marker.fromJSONObject and TextSegment.fromJSONObject argument types have been corrected -Previously, the arguments of Marker.fromJSONObject and TextSegment.fromJSONObject were of type `any`. Now, the argument for the Marker implementation is of type `IJSONSegment` and the argument for the TextSegment implementation is of type `string | IJSONSegment`. +Previously, the arguments of `Marker.fromJSONObject` and `TextSegment.fromJSONObject` were of type `any`. However, at +runtime only certain types were expected and using other types would cause errors. + +Now, the argument for the Marker implementation is of type `IJSONSegment` and the argument for the TextSegment +implementation is of type `string | IJSONSegment`. This reflects actual runtime support. + +This change should have no impact on existing code unless the code is using incorrect types. Such code already does not +function and should be corrected. diff --git a/.changeset/khaki-hairs-vanish.md b/.changeset/khaki-hairs-vanish.md index 9f990b9ccd9..905611d52e0 100644 --- a/.changeset/khaki-hairs-vanish.md +++ b/.changeset/khaki-hairs-vanish.md @@ -1,11 +1,18 @@ --- -"fluid-framework": patch -"@fluidframework/map": patch +"fluid-framework": minor +"@fluidframework/map": minor --- -Map API documentation updates +Some SharedDirectory/SharedMap-related APIs have been sealed + +Note that this is a _documentation only change._ There is no runtime or type-level impact. + +Some top-level APIs within `@fluidframework/map` and `fluid-framework` have been updated to reflect their +sealed/readonly nature. That is, they are not to be implemented externally to Fluid Framework and not changed. This was +already the case, but the documentation was not clear. + +Updated APIs: -Remaining top-level APIs within `@fluidframework/map` have had docs updated to reflect their sealed/readonly nature, i.e. they are not to be implemented externally to Fluid Framework and not changed, as has already been the case. Impacted APIs: - [IDirectory](https://fluidframework.com/docs/api/v2/fluid-framework/idirectory-interface) sealed - [IDirectoryEvents](https://fluidframework.com/docs/api/v2/fluid-framework/idirectoryevents-interface) sealed - [IDirectoryValueChanged](https://fluidframework.com/docs/api/v2/fluid-framework/idirectoryvaluechanged-interface) sealed and path property is readonly diff --git a/.changeset/silly-planets-wait.md b/.changeset/silly-planets-wait.md index f975b00d2ae..59527ba57be 100644 --- a/.changeset/silly-planets-wait.md +++ b/.changeset/silly-planets-wait.md @@ -3,6 +3,6 @@ "@fluidframework/tree": minor --- -New feature: Debug visualizers for TreeNodes in NodeJS and browsers +✨ New! Debug visualizers for TreeNodes in NodeJS and browsers TreeNodes now have custom debug visualizers to improve the debug experience in NodeJS and in browsers. Note that custom formatters must be enabled in the browser developer tools for that visualizer to be used. diff --git a/.changeset/stale-rooms-bow.md b/.changeset/stale-rooms-bow.md index 9e40709e712..e4775448147 100644 --- a/.changeset/stale-rooms-bow.md +++ b/.changeset/stale-rooms-bow.md @@ -3,6 +3,7 @@ "@fluidframework/tree": minor --- -Using "delete" on tree fields now errors instead of not working correctly. +Using "delete" on tree fields now throws an error instead of not working correctly -TypeScript allows "delete" on object node optional fields if "exactOptionalPropertyTypes" is not enabled. This does not work correctly at runtime and now produces an informative error. +TypeScript allows `delete` on object node optional fields if the `exactOptionalPropertyTypes` tsconfig setting is not +enabled. This does not work correctly at runtime and now produces an informative error. diff --git a/.changeset/terrific-apples-run.md b/.changeset/terrific-apples-run.md index ab52c97f1fe..9306853e120 100644 --- a/.changeset/terrific-apples-run.md +++ b/.changeset/terrific-apples-run.md @@ -2,4 +2,10 @@ "@fluidframework/tree": minor --- -Adds garbage collection for repair data so that removed content is not retained forever. This is mostly an internal change so users of SharedTree won't need to adapt any code but it could cause an issue with cross-version collab where an older version does not send a refresher that a newer version may need. In this case, a "refresher data not found" error will be thrown. +SharedTree content that is removed is now deleted + +SharedTree now supports garbage collection so that removed content is not retained forever. +This is an internal change and users of SharedTree won't need to adapt any existing code. + +This change could cause errors with cross-version collaboration where an older client does not send data that a newer +version may need. In this case, a "refresher data not found" error will be thrown. diff --git a/RELEASE_NOTES/2.1.0.md b/RELEASE_NOTES/2.1.0.md new file mode 100644 index 00000000000..46dd959be67 --- /dev/null +++ b/RELEASE_NOTES/2.1.0.md @@ -0,0 +1,144 @@ + + +# Fluid Framework v2.1.0 + +## ✨ New Features + +### Type guards for DDS types + +In the 2.0 release of Fluid, the concrete class implementations for DDSes were hidden from Fluid's API surface. This made `instanceof` checks fail to work correctly. There were ways to work around this in application code, but they involved boilerplate which required more understanding of Fluid internals than should be necessary. + +There is now a drop-in replacement to `instanceof`: the static `.is()` method to `SharedObjectKind`, which is available on all DDSes. For example: + +```typescript +// Works in Fluid Framework 1.0 but not in the initial release of Fluid Framework 2.0: +if (myObject instanceof SharedString) { + // do something +} + +// In Fluid Framework 2.0 and beyond, that code can now be written like so: +if (SharedString.is(myObject)) { + // do something +} +``` + +#### Packages affected + +- @fluidframework/shared-object-base + +## 🌳 SharedTree DDS changes + +### Using "delete" on tree fields now throws an error instead of not working correctly + +TypeScript allows `delete` on object node optional fields if the `exactOptionalPropertyTypes` tsconfig setting is not enabled. This does not work correctly at runtime and now produces an informative error. + +#### Packages affected + +- fluid-framework +- @fluidframework/tree + +### Detect arrayNode iterator invalidation + +When `arrayNode`s are edited concurrently during iteration, an error will be thrown. + +#### Packages affected + +- @fluidframework/tree +- fluid-framework + +### SharedTree content that is removed is now deleted + +SharedTree now supports garbage collection so that removed content is not retained forever. This is an internal change and users of SharedTree won't need to adapt any existing code. + +This change could cause errors with cross-version collaboration where an older client does not send data that a newer version may need. In this case, a "refresher data not found" error will be thrown. + +#### Packages affected + +- @fluidframework/tree + +### tree: Improved performance for accessing identifiers in shortId API + +Users should see improved performance when calling the `Tree.shortId` API. Identifier field keys are now cached in the schema for faster access. + +#### Packages affected + +- fluid-framework +- @fluidframework/tree + +### Improved error reporting + +Several cases of invalid usage patterns for tree APIs have gained improved error reporting, as well as improved documentation on the APIs detailing what usage is supported. These improvements include: + +- Unsupported usages of schema classes: using more than one schema class derived from a single SchemaFactory generated base class. This used to hit internal asserts, but now has a descriptive user-facing UsageError. Most of this work was done in [9fb3dcf](https://github.com/microsoft/FluidFramework/commit/9fb3dcf491a7f0d66f4abbdc64ab97ccabef4707). + +- Improved detection of when prior exception may have left SharedTree in an invalid state. These cases now report a UsageError including a reference to the prior exception. This was mainly done in [9fb3dcf](https://github.com/microsoft/FluidFramework/commit/9fb3dcf491a7f0d66f4abbdc64ab97ccabef4707) and [b77d530](https://github.com/microsoft/FluidFramework/commit/b77d530b9252201c40a90d1a2a6315f76f1a4a4b). + +#### Packages affected + +- fluid-framework +- @fluidframework/tree + +### ✨ New! Debug visualizers for TreeNodes in NodeJS and browsers + +TreeNodes now have custom debug visualizers to improve the debug experience in NodeJS and in browsers. Note that custom formatters must be enabled in the browser developer tools for that visualizer to be used. + +#### Packages affected + +- fluid-framework +- @fluidframework/tree + +## 🐛 Bug Fixes + +### tinylicious-client: Promote APIs from beta to public + +Some tinylicious-client APIs were marked beta in previous releases. These APIs are now correctly marked public and also sealed to indicate they are not to be implemented externally to Fluid Framework and not changed. + +Updated APIs: + +- [ITinyliciousAudience](https://fluidframework.com/docs/api/v2/tinylicious-client/itinyliciousaudience-typealias) sealed +- [TinyliciousClient](https://fluidframework.com/docs/api/v2/tinylicious-client/tinyliciousclient-class) sealed +- [TinyliciousClientProps](https://fluidframework.com/docs/api/v2/tinylicious-client/tinyliciousclientprops-interface) sealed +- [TinyliciousConnectionConfig](https://fluidframework.com/docs/api/v2/tinylicious-client/tinyliciousconnectionconfig-interface) sealed +- [TinyliciousContainerServices](https://fluidframework.com/docs/api/v2/tinylicious-client/tinyliciouscontainerservices-interface) sealed +- [TinyliciousMember](https://fluidframework.com/docs/api/v2/tinylicious-client/tinyliciousmember-interface) sealed +- [TinyliciousUser](https://fluidframework.com/docs/api/v2/tinylicious-client/tinylicioususer-interface) sealed + +#### Packages affected + +- @fluidframework/tinylicious-client + +### merge-tree: The Marker.fromJSONObject and TextSegment.fromJSONObject argument types have been corrected + +Previously, the arguments of `Marker.fromJSONObject` and `TextSegment.fromJSONObject` were of type `any`. However, at runtime only certain types were expected and using other types would cause errors. + +Now, the argument for the Marker implementation is of type `IJSONSegment` and the argument for the TextSegment implementation is of type `string | IJSONSegment`. This reflects actual runtime support. + +This change should have no impact on existing code unless the code is using incorrect types. Such code already does not function and should be corrected. + +#### Packages affected + +- @fluidframework/merge-tree + +### Some SharedDirectory/SharedMap-related APIs have been sealed + +Note that this is a _documentation only change._ There is no runtime or type-level impact. + +Some top-level APIs within `@fluidframework/map` and `fluid-framework` have been updated to reflect their sealed/readonly nature. That is, they are not to be implemented externally to Fluid Framework and not changed. This was already the case, but the documentation was not clear. + +Updated APIs: + +- [IDirectory](https://fluidframework.com/docs/api/v2/fluid-framework/idirectory-interface) sealed +- [IDirectoryEvents](https://fluidframework.com/docs/api/v2/fluid-framework/idirectoryevents-interface) sealed +- [IDirectoryValueChanged](https://fluidframework.com/docs/api/v2/fluid-framework/idirectoryvaluechanged-interface) sealed and path property is readonly +- [ISharedDirectory](https://fluidframework.com/docs/api/v2/fluid-framework/ishareddirectory-interface) sealed +- [ISharedDirectoryEvents](https://fluidframework.com/docs/api/v2/fluid-framework/ishareddirectoryevents-interface) sealed +- [IValueChanged](https://fluidframework.com/docs/api/v2/fluid-framework/ivaluechanged-interface) sealed + +#### Packages affected + +- fluid-framework +- @fluidframework/map + +### 🛠️ Start Building Today! + +Please continue to engage with us on GitHub [Discussion](https://github.com/microsoft/FluidFramework/discussions) and [Issue](https://github.com/microsoft/FluidFramework/issues) pages as you adopt Fluid Framework!