Merge branch 'main' into praggarg/remove-deprecated-summaryprotocol

.changeset/real-grapes-kick.md

@@ -0,0 +1,41 @@
+---
+"@fluidframework/merge-tree": minor
+"@fluidframework/sequence": minor
+---
+---
+"section": deprecation
+---
+
+Merge-Tree and SharedString ISegment Deprecations
+
+The current ISegment interface over-exposes a number of properties which do not have an external use case, and any external usage could result in damage to the underlying merge-tree including data corruption.
+
+The only use case that will continue to be supported is determining if a segment is removed. For this purpose we've added the free function `segmentIsRemoved(segment: ISegment): boolean`.
+
+For example, checking if a segment is not removed would change as follows:
+``` diff
+- if(segment.removedSeq === undefined){
++ if(!segmentIsRemoved(segment)){
+```
+
+The following properties are deprecated on ISegment and its implementations:
+- clientId
+- index
+- localMovedSeq
+- localRefs
+- localRemovedSeq
+- localSeq
+- movedClientsIds
+- movedSeq
+- movedSeqs
+- ordinal
+- removedClientIds
+- removedSeq
+- seq
+- wasMovedOnInsert
+
+Additionally, the following types are also deprecated, and will become internal (i.e. users of the Fluid Framework will not have access to them):
+- IMergeNodeCommon
+- IMoveInfo
+- IRemovalInfo
+- LocalReferenceCollection

docs/README.md

@@ -168,6 +168,64 @@ Rationale:
 
 For more details about leveraging Mermaid diagrams in Docusaurus, see [here](https://docusaurus.io/docs/markdown-features/diagrams).
 
+### Documents vs Pages
+
+_Documents_ and _Pages_ are distinct concepts in Docusaurus.
+For an overview of each, see: [Documents](https://docusaurus.io/docs/docs-introduction) and [Pages](https://docusaurus.io/docs/creating-pages).
+
+Some primary distinctions:
+
+1. _Documents_ live under `docs` and `versioned_docs`. _Pages_ live under `src/pages`.
+1. _Documents_ are versioned. _Pages_ are not.
+
+### The Sidebar
+
+For an overview of how to configure sidebars in Docusaurus, see [here](https://docusaurus.io/docs/sidebar).
+
+The site's "current" version sidebar is configured via `sidebars.ts`.
+
+Sidebars for other versions are configured via `versioned_sidebars/version-<version-id>.json`.
+
+-   Versioned sidebars do not yet support JS/TS file formats.
+    See <https://github.com/facebook/docusaurus/issues/10407>.
+
+Note that sidebars are configured for documents under `docs` and `versioned_docs`; they do not apply to unversioned _Pages_.
+
+### Documentation Versioning
+
+For an overview of Docusaurus's versioning functionality, see [here](https://docusaurus.io/docs/versioning).
+
+We currently offer versioned documentation for each of our supported major versions.
+This documentation is intended to be kept up-to-date with the most recent release of each major version series.
+
+For now, this means we publish documentation (including generated API documentation) for versions `1.x` and `2.x`.
+
+-   We also support generating API documentation for the local repo code in local development only.
+    See [Local API docs build](#local-api-docs-build), but these are not intended to be published.
+
+#### Why Only Major Versions?
+
+We aim to keep the number of concurrently maintained site versions minimized, for a number of reasons:
+
+1. Developer overhead - the more versions of the docs we offer, the more work we take on to keep documentation for supported versions up to date.
+2. User overhead - the more versions we offer, the more users have to think about when they engage with our website.
+3. Build performance - Docusaurus's build isn't fast. The more versions we add to our suite, the longer our build times become.
+
+#### Updating the Site Version
+
+These steps are based on Docusaurus's tutorial [here](https://docusaurus.io/docs/versioning#tutorials).
+
+Note: generating the API documentation for the new "current" version will fail if the release branch for that version has not yet been created.
+
+1. Run `npx --no-install docusaurus docs:version v<current-major-version-number>` from the root of this directory.
+   E.g., `... docusaurus docs:version v2` when prepping for `v3` documentation.
+    - This will copy the contents of `docs` into `versioned_docs` under the specified version ID.
+    - This will also generate a sidebar configuration for the copied version under `versioned_sidebars`.
+1. Update `config/docs-versions.mjs` to update the version ID for the "current" version, and add the newly frozen version to the `otherVersions` list.
+   This will automatically update aspects of the site, including:
+    1. Which versions of the API documentation are generated during the build
+    1. The version selection drop-down in the site header
+
 ### Best practices
 
 #### Markdown

docs/docs/build/audience.mdx

@@ -5,7 +5,7 @@ sidebar_position: 8
 
 The audience is the collection of users connected to a container. When your app creates a container using a service-specific client library, the app is provided with a service-specific audience object for that container as well. Your code can query the audience object for connected users and use that information to build rich and collaborative user presence features.
 
-This document will explain how to use the audience APIs and then provide examples on how to use the audience to show user presence. For anything service-specific, the [Tinylicious](/docs/testing/tinylicious) Fluid service is used.
+This document will explain how to use the audience APIs and then provide examples on how to use the audience to show user presence. For anything service-specific, the [Tinylicious](../testing/tinylicious.mdx) Fluid service is used.
 
 ## Working with the audience
 
@@ -100,7 +100,7 @@ While the audience is the foundation for user presence features, the list of con
 
 Most presence scenarios will involve data that only a single user or client knows and needs to communicate to other audience members. Some of those scenarios will require the app to save data for each user for future sessions. For example, consider a scenario where you want to display how long each user has spent in your application. An active user's time should increment while connected, pause when they disconnect, and resume once they reconnect. This means that the time each user has spent must be persisted so it can survive disconnections.
 
-One option is to use a `SharedMap` object with a `SharedCounter` object as the value onto which each user will increment their time spent every minute (also see [Introducing distributed data structures](./dds)). All other connected users will then receive changes to that SharedMap automatically. Your app's UI can display data from the map for only users present in the audience. A returning user can find themselves in the map and resume from the latest state.
+One option is to use a `SharedMap` object with a `SharedCounter` object as the value onto which each user will increment their time spent every minute (also see [Introducing distributed data structures](./dds.mdx)). All other connected users will then receive changes to that SharedMap automatically. Your app's UI can display data from the map for only users present in the audience. A returning user can find themselves in the map and resume from the latest state.
 
 #### Shared transient data
 

docs/docs/build/auth.mdx

@@ -5,4 +5,4 @@ sidebar_position: 4
 
 Security is critical to modern web applications. Fluid Framework, as a part of your web application architecture, is an important piece of infrastructure to secure. Fluid Framework is a layered architecture, and auth-related concepts are implemented based on the Fluid service it's connecting to. This means that the specifics of authentication will differ based on the Fluid service.
 
-To learn how authentication and authorization works in Azure Fluid Relay, see [Authentication and authorization in your app](https://docs.microsoft.com/azure/azure-fluid-relay/concepts/authentication-authorization). Other Fluid services may differ. See [Available Fluid services](../deployment/service-options) for more information.
+To learn how authentication and authorization works in Azure Fluid Relay, see [Authentication and authorization in your app](https://docs.microsoft.com/azure/azure-fluid-relay/concepts/authentication-authorization). Other Fluid services may differ. See [Available Fluid services](../deployment/service-options.mdx) for more information.

docs/docs/build/container-states-events.mdx

@@ -5,7 +5,7 @@ sidebar_position: 3
 
 import { ApiLink } from "@site/src/components/shortLinks";
 
-This article provides a detailed description of the lifecycle states of the containers and container events. It assumes that you are familiar with [Containers](./containers).
+This article provides a detailed description of the lifecycle states of the containers and container events. It assumes that you are familiar with [Containers](./containers.mdx).
 
 :::note
 
@@ -56,16 +56,16 @@ Details are below the diagram.
 
 #### Unpublished
 
-When a [container is created](./containers#creating-a-container), it is in **unpublished** state and exists only on the creating client.
+When a [container is created](./containers.mdx#creating-a-container), it is in **unpublished** state and exists only on the creating client.
 
-Users, or your code, can start editing the data in the container right away, but the data is not shareable with other clients until the [container is published](./containers#publishing-a-container).
+Users, or your code, can start editing the data in the container right away, but the data is not shareable with other clients until the [container is published](./containers.mdx#publishing-a-container).
 Use the unpublished state to create initial data to populate your shared objects if needed.
 This is often useful in scenarios where you want to make sure that all connected clients have a coherent initial state.
 For example, if collaboration involves tables, your code can set a minimum table size.
 
 #### Publishing
 
-A container transitions to **publishing** state when `container.attach` method is called on the creating client. For details, see [Publishing a container](./containers#publishing-a-container). It is normally in this state only very briefly and then automatically transitions to **published** state when publication is complete.
+A container transitions to **publishing** state when `container.attach` method is called on the creating client. For details, see [Publishing a container](./containers.mdx#publishing-a-container). It is normally in this state only very briefly and then automatically transitions to **published** state when publication is complete.
 
 :::note
 
@@ -76,7 +76,7 @@ In the Fluid APIs, the terms "attach", "attaching", "attached" and "detached" me
 #### Published to the service
 
 When publishing completes, the container is **published**, so it exists in the Fluid service as well as the creating client.
-Subsequent clients can [connect to the container](./containers#connecting-to-a-container), synchronize with its latest data values, and edit them.
+Subsequent clients can [connect to the container](./containers.mdx#connecting-to-a-container), synchronize with its latest data values, and edit them.
 
 A container can never transition back to an unpublished state, but it can transition to a deleted state.
 
@@ -241,10 +241,10 @@ In this state, the client is attempting to connect to the Fluid service, but has
 A container moves into the **establishing connection** state in any of the following circumstances:
 
 -   On the creating client, your code calls the `container.attach` method.
-    For more information, see [Publishing a container](./containers#publishing-a-container).
+    For more information, see [Publishing a container](./containers.mdx#publishing-a-container).
     This method publishes the container _and_ connects the client to the service.
 -   Your code calls the client's `getContainer` method on a client that has not previously been connected.
-    For more information, see [Connecting to a container](./containers#connecting-to-a-container).
+    For more information, see [Connecting to a container](./containers.mdx#connecting-to-a-container).
 -   The Fluid client runtime tries to reconnect following a disconnection caused by a network problem.
 -   Your code calls the `container.connect` method on a client that had become disconnected.
 

docs/docs/build/containers.mdx

@@ -31,7 +31,7 @@ The device is a subsequent client in all future sessions.
 
 Your code creates containers using APIs provided by a service-specific client library.
 Each service-specific client library implements a common API for manipulating containers.
-For example, the [Tinylicious library](/docs/testing/tinylicious) provides <PackageLink packageName="tinylicious-client">these APIs</PackageLink> for the Tinylicious Fluid service.
+For example, the [Tinylicious library](../testing/tinylicious.mdx) provides <PackageLink packageName="tinylicious-client">these APIs</PackageLink> for the Tinylicious Fluid service.
 These common APIs enable your code to specify what shared objects should live in the `FluidContainer`, and to connect to the container once it is created.
 
 ### Container schema
@@ -44,7 +44,7 @@ A schema can specify:
 -   Some initial shared objects that are created as soon as the container is created, and are immediately and always available to all connected clients.
 -   The types of shared objects that can be added to the container at runtime and made available for use by all connected clients.
 
-As explained below, the same schema definition that is used to create the container must be provided when clients subsequently connect to the container. For more information about initial objects and dynamic object creation see [Data modeling](./data-modeling).
+As explained below, the same schema definition that is used to create the container must be provided when clients subsequently connect to the container. For more information about initial objects and dynamic object creation see [Data modeling](./data-modeling.mdx).
 
 This example schema defines two initial objects, `layout` and `text`, and declares that objects of the distributed data structure (DDS) types `SharedCell` and `SharedString` can be created at runtime.
 
@@ -77,7 +77,7 @@ Notes:
 -   The `client` object is defined by the service-specific client library. See the documentation for the service you are using for more details about how to use its service-specific client library.
 -   It is a good practice to destructure the object that is returned by `createContainer` into its two main parts; `container` and `services`. For more about the `services` object, see [Container services](#container-services).
 
-A newly created container is in an **unpublished** state. An unpublished container is stored on the local client only and therefore no data is shared with other clients yet. But the data in it can, and sometimes should be, edited while it is unpublished. See [Container states and events](./container-states-events).
+A newly created container is in an **unpublished** state. An unpublished container is stored on the local client only and therefore no data is shared with other clients yet. But the data in it can, and sometimes should be, edited while it is unpublished. See [Container states and events](./container-states-events.mdx).
 
 ### Publishing a container
 
@@ -94,7 +94,7 @@ Once published, the Fluid container becomes an entity on Fluid service and subse
 Invoking the container's `attach` method returns the unique identifier for the container.
 Subsequent clients use this ID to connect to the container.
 
-Note that once published, a container cannot be unpublished. (But it can be deleted. See [Deleting a container from the service](./container-states-events#deleting-a-container-from-the-service).)
+Note that once published, a container cannot be unpublished. (But it can be deleted. See [Deleting a container from the service](./container-states-events.mdx#deleting-a-container-from-the-service).)
 
 ```typescript {linenos=inline,hl_lines=[10]}
 const schema = {
@@ -108,7 +108,7 @@ const { container, services } = await client.createContainer(schema);
 const containerId = await container.attach();
 ```
 
-In addition to publishing the container, the `attach` method also connects the creating client to the published container. See [Connecting to a container](#connecting-to-a-container) and [Connection status states](./container-states-events#connection-status-states).
+In addition to publishing the container, the `attach` method also connects the creating client to the published container. See [Connecting to a container](#connecting-to-a-container) and [Connection status states](./container-states-events.mdx#connection-status-states).
 
 ### Connecting to a container
 
@@ -131,7 +131,7 @@ const { container, services } =
 
 :::tip
 
-This section provides only basic information about the _most important_ states that a container can be in. Details about _all_ container states, including state diagrams, state management, editing management, and container event handling are in [Container states and events](./container-states-events).
+This section provides only basic information about the _most important_ states that a container can be in. Details about _all_ container states, including state diagrams, state management, editing management, and container event handling are in [Container states and events](./container-states-events.mdx).
 
 :::
 
@@ -191,4 +191,4 @@ For example, consider an education application where multiple teachers collabora
 
 When you create or connect to a container with `createContainer` or `getContainer`, the Fluid service will also return a service-specific _services_ object.
 This object contains references to useful services you can use to build richer applications.
-An example of a container service is the [Audience](./audience), which provides user information for clients that are connected to the container. See [Working with the audience](./audience#working-with-the-audience) for more information.
+An example of a container service is the [Audience](./audience.mdx), which provides user information for clients that are connected to the container. See [Working with the audience](./audience.mdx#working-with-the-audience) for more information.

docs/docs/build/data-modeling.mdx

@@ -24,7 +24,7 @@ The example below creates a new container with a `SharedMap` and a `SharedCell`
 About this code note:
 
 -   `client` represents an object defined by the service-specific client library. See the documentation for the service you are using for more details about how to use its service-specific client library.
--   It is a good practice to deconstruct the object that is returned by `createContainer` into its two main parts; `container` and `services`. For an example of the use of the latter, see [Working with the audience](./audience#working-with-the-audience).
+-   It is a good practice to deconstruct the object that is returned by `createContainer` into its two main parts; `container` and `services`. For an example of the use of the latter, see [Working with the audience](./audience.mdx#working-with-the-audience).
 
 ```typescript
 const schema = {
@@ -131,7 +131,7 @@ map.on("valueChanged", (changed) => {
 }
 ```
 
-For more information about handles see [Handles](../concepts/handles).
+For more information about handles see [Handles](../concepts/handles.mdx).
 
 ### When to use dynamic objects