docs(tree): Update undo and detach trees docs #20754
Conversation
github-actions
bot
added
area: dds
|
|
||
| Keeping all detached trees forever would lead to unbounded memory growth in clients, | ||
| and would run the risk of seriously bloating the document's snapshot size. | ||
| In order to avoid that, we intend to |
There was a problem hiding this comment.
"In order to avoid that, detached trees will be garbage collected (though this is not yet implemented as of May 2024)."
| become relevant again. | ||
| There are four scenarios where this can happen: | ||
|
|
||
| - Updating the view after reverting a commit |
There was a problem hiding this comment.
What does "updating the view" mean here? Why is it relevant? Don't we want to update the forest for a checkout during rebases, etc. regardless of whether or not the "view" is updating?
There was a problem hiding this comment.
Sorry, "view" mean TreeCheckout to me because I experience our system at a lower level. Fixed.
| - New trees can be created | ||
| - Trees are never deleted, but clients are allowed to forget their existence/contents | ||
| - Clients can refresh one-another on the existence and contents of trees | ||
| - One that is concerned with the location of nodes with respect to one-another: |
There was a problem hiding this comment.
I don't quite understand this paradigm. I think I sort of see the conceptual difference, but aren't the two concerns still quite interelated? For example, if a tree "moves" - allegedly the concern of the second DDS - but it is moved underneath another tree, then now it is part of that tree and no longer exists as a detached root (right?) and therefore the first DDS would want to remove it, so it's also a concern of the first DDS. I am probably missing something; I didn't gain any clarity from thinking about it as these two different concerns.
There was a problem hiding this comment.
Perhaps it would be more accurate to say that both DDSes deal with nodes. Moving a node does not remove it in the eyes of the first DDS.
| The `Forest`, `AnchorSet`, and `DeltaVisitor` abstractions do not feature the concept of detached tree. | ||
| At this layer, we identify detached trees using a path that starts in a detached field. | ||
| (The same kind of field as the one that contains the root of the document.) | ||
| We may decide to force these abstractions to adopt the concept detached tree in the future if we see a benefit. |
There was a problem hiding this comment.
| We may decide to force these abstractions to adopt the concept detached tree in the future if we see a benefit. | |
| We may decide to force these abstractions to adopt the concept of a detached tree in the future if we see a benefit. |
|
|
||
| While this would work, it has the following drawbacks: | ||
|
|
||
| 1. The overhear per detached tree may be prohibitive in scenarios (like text editing) |
There was a problem hiding this comment.
| 1. The overhear per detached tree may be prohibitive in scenarios (like text editing) | |
| 1. The overhead per detached tree may be prohibitive in scenarios (like text editing) |
| This is not currently an issue because we do have that ability, | ||
| but it is possible we will want to allow `Forest`s to have their own (more efficient) scheme for identifying them. | ||
| This point is weak on its own, but it provides an incentive to pick an approach that, | ||
| on top of addressing point 1, also addresses it. |
There was a problem hiding this comment.
| on top of addressing point 1, also addresses it. | |
| on top of addressing point 1, also addresses this concern. |
Description
Retire "repair data" terminology, and adopt "detached trees" instead.
Update the docs to match the current design.
Breaking Changes
None
Reviewer Guidance
I highly recommend ignoring the diff for v1-undo.md. Just read the whole file.
Future Work
Update undo.md to extend the concept of undo window to detached trees.
Add a user-facing document on undo semantics.