MergeTree: Deprecate segmentGroups and ack on ISegment (microsoft#22212)

# Deprecate segmentGroups and ack on ISegment

The `SegmentGroupCollection` class, along with the `segmentGroups`
property and `ack` function on segments, are not intended for external
use.
These elements will be removed in a future release for the following
reasons:

 * There are no scenarios where they need to be used directly.
 * Using them directly will cause eventual consistency problems.
 * Upcoming features will require modifications to these mechanisms.

.changeset/two-guests-add.md

@@ -0,0 +1,14 @@
+---
+"@fluidframework/merge-tree": minor
+---
+---
+"section": "deprecation"
+---
+Deprecate segmentGroups and ack on ISegment
+
+The `SegmentGroupCollection` class, along with the `segmentGroups` property and `ack` function on segments, are not intended for external use.
+These elements will be removed in a future release for the following reasons:
+
+ * There are no scenarios where they need to be used directly.
+ * Using them directly will cause eventual consistency problems.
+ * Upcoming features will require modifications to these mechanisms.

packages/dds/merge-tree/api-report/merge-tree.legacy.alpha.api.md

@@ -19,7 +19,7 @@ export interface AttributionPolicy {
 // @alpha (undocumented)
 export abstract class BaseSegment implements ISegment {
     constructor(properties?: PropertySet);
-    // (undocumented)
+    // @deprecated (undocumented)
     ack(segmentGroup: SegmentGroup, opArgs: IMergeTreeDeltaOpArgs): boolean;
     // @deprecated
     addProperties(newProps: PropertySet, seq?: number, collaborating?: boolean, rollback?: PropertiesRollback): PropertySet;
@@ -71,7 +71,7 @@ export abstract class BaseSegment implements ISegment {
     removedClientIds?: number[];
     // (undocumented)
     removedSeq?: number;
-    // (undocumented)
+    // @deprecated (undocumented)
     readonly segmentGroups: SegmentGroupCollection;
     // (undocumented)
     seq: number;
@@ -445,6 +445,7 @@ export interface IRemovalInfo {
 
 // @alpha
 export interface ISegment extends IMergeNodeCommon, Partial<IRemovalInfo>, Partial<IMoveInfo> {
+    // @deprecated (undocumented)
     ack(segmentGroup: SegmentGroup, opArgs: IMergeTreeDeltaOpArgs): boolean;
     // @deprecated
     addProperties(newProps: PropertySet, seq?: number, collaborating?: boolean, rollback?: PropertiesRollback): PropertySet;
@@ -465,7 +466,7 @@ export interface ISegment extends IMergeNodeCommon, Partial<IRemovalInfo>, Parti
     properties?: PropertySet;
     // @deprecated
     propertyManager?: PropertiesManager;
-    // (undocumented)
+    // @deprecated (undocumented)
     readonly segmentGroups: SegmentGroupCollection;
     seq?: number;
     // (undocumented)
@@ -712,7 +713,7 @@ export interface SegmentGroup {
     segments: ISegment[];
 }
 
-// @alpha (undocumented)
+// @alpha @deprecated (undocumented)
 export class SegmentGroupCollection {
     constructor(segment: ISegment);
     // (undocumented)

packages/dds/merge-tree/src/mergeTreeNodes.ts

@@ -26,6 +26,7 @@ import {
 	refGetTileLabels,
 	refTypeIncludesFlag,
 } from "./referencePositions.js";
+// eslint-disable-next-line import/no-deprecated
 import { SegmentGroupCollection } from "./segmentGroupCollection.js";
 // eslint-disable-next-line import/no-deprecated
 import { PropertiesManager, PropertiesRollback } from "./segmentPropertiesManager.js";
@@ -183,6 +184,10 @@ export function toMoveInfo(maybe: Partial<IMoveInfo> | undefined): IMoveInfo | u
  */
 export interface ISegment extends IMergeNodeCommon, Partial<IRemovalInfo>, Partial<IMoveInfo> {
 	readonly type: string;
+	/**
+	 * @deprecated - This property should not be used externally and will be removed in a subsequent release.
+	 */
+	// eslint-disable-next-line import/no-deprecated
 	readonly segmentGroups: SegmentGroupCollection;
 	readonly trackingCollection: TrackingGroupCollection;
 	/**
@@ -290,6 +295,7 @@ export interface ISegment extends IMergeNodeCommon, Partial<IRemovalInfo>, Parti
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	toJSONObject(): any;
 	/**
+	 * @deprecated - This function should not be used externally and will be removed in a subsequent release.
 	 * Acks the current segment against the segment group, op, and merge tree.
 	 *
 	 * @param segmentGroup - Pending segment group associated with this op.
@@ -515,6 +521,11 @@ export abstract class BaseSegment implements ISegment {
 	public ordinal: string = "";
 	public cachedLength: number = 0;
 
+	/**
+	 * {@inheritdoc ISegment.segmentGroups}
+	 * @deprecated - This property should not be used externally and will be removed in a subsequent release.
+	 */
+	// eslint-disable-next-line import/no-deprecated
 	public readonly segmentGroups: SegmentGroupCollection = new SegmentGroupCollection(this);
 	public readonly trackingCollection: TrackingGroupCollection = new TrackingGroupCollection(
 		this,
@@ -602,6 +613,10 @@ export abstract class BaseSegment implements ISegment {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	public abstract toJSONObject(): any;
 
+	/**
+	 * {@inheritdoc ISegment.ack}
+	 * @deprecated - This function should not be used externally and will be removed in a subsequent release.
+	 */
 	public ack(segmentGroup: SegmentGroup, opArgs: IMergeTreeDeltaOpArgs): boolean {
 		const currentSegmentGroup = this.segmentGroups.dequeue();
 		assert(

packages/dds/merge-tree/src/segmentGroupCollection.ts

@@ -8,8 +8,11 @@ import { DoublyLinkedList, walkList } from "./collections/index.js";
 import { ISegment, SegmentGroup } from "./mergeTreeNodes.js";
 
 /**
+ * @deprecated - This class should not be used externally and will be removed in a subsequent release.
  * @legacy
  * @alpha
+ *
+ * @privateRemarks After the deprecation period this class should be remove from this package's exports, and only be used internally
  */
 export class SegmentGroupCollection {
 	// eslint-disable-next-line import/no-deprecated