docs(tree): merge semantics docs for each node kind

[yann-achard-MS]

Description

Adds documentation describing the merge semantics of operations on each node kind in the tree.

Breaking Changes

None

[msfluid-bot]

Code Coverage Summary

No packages impacted by the change.

---

Baseline commit: c7730cc
Baseline build: 306006
Happy Coding!!

Code coverage comparison check passed!!

[msfluid-bot]

⯅ @fluid-example/bundle-size-tests: +245 Bytes

Metric Name	Baseline Size	Compare Size	Size Diff
aqueduct.js	464.33 KB	464.36 KB	⯅ +35 Bytes
azureClient.js	563.18 KB	563.23 KB	⯅ +49 Bytes
connectionState.js	724 Bytes	724 Bytes	■ No change
containerRuntime.js	262.48 KB	262.5 KB	⯅ +14 Bytes
fluidFramework.js	426.84 KB	426.85 KB	⯅ +14 Bytes
loader.js	134.18 KB	134.19 KB	⯅ +14 Bytes
map.js	42.71 KB	42.71 KB	⯅ +7 Bytes
matrix.js	148.36 KB	148.36 KB	⯅ +7 Bytes
odspClient.js	528.97 KB	529.02 KB	⯅ +49 Bytes
odspDriver.js	97.88 KB	97.9 KB	⯅ +21 Bytes
odspPrefetchSnapshot.js	42.81 KB	42.83 KB	⯅ +14 Bytes
sharedString.js	164.26 KB	164.27 KB	⯅ +7 Bytes
sharedTree.js	417.3 KB	417.3 KB	⯅ +7 Bytes
Total Size	3.37 MB	3.37 MB	⯅ +245 Bytes

---

Baseline commit: c7730cc

Generated by 🚫 dangerJS against 97ada18

[alexvy86]

Mostly minor notes, a few bits of more relevant feedback. Also, I think these docs really should find their way to fluidframework.com. cc @Josmithr @rohandubal

[alexvy86]

Nit, the first line is shorter than it could be and the second one longer. (I'm assuming you split them based on known conventions like 80 char lines, or IDE rulers; that's what I normally do).

[yann-achard-MS]

No, I'm splitting based on gramatically independent clauses (whith the hope of making it easier to do line-by-line review).
For example I can't split that long line into a standalone clause.

[alexvy86]

Interesting, I hadn't seen that approach before, but I can see the appeal.

[noencke]

I do the same FWIW. I split on sentences, and if I have a very long sentence then I'll split over a comma, and if there are no commas then I'll do what Yann did. Though, I'm starting to let my lines be longer and longer these days. Both viewers and editors have line wrap if you want them, so often the only practical advantage to splitting up the lines is to reduce merge conflicts, and that just doesn't happen that often with doc files.

[Josmithr]

Breaking on sentence boundaries is documented as a best practice in our github wiki.
https://github.com/microsoft/FluidFramework/wiki/Markdown-Best-Practices#line-breaks-along-sentence-boundaries

[alexvy86]

Maybe add a footnote or something to indicate what would happen if Bob's operation is NACKed? The color would go back to red, I... think/hope? 😄 .

Also, do we need the <br/> here and a few lines above?

[yann-achard-MS]

Actually, I don't think we support that in SharedTree. Once you've allowed an edit to be sent for sequencing, we forever re-try until you close the session.
I agree that may not always be ideal.

[alexvy86]

Just realized Github helpfully [cough] rendered the <br/>, so I think the question stands, do we actually need them in md files?

[Josmithr]

For the image files, if possible, we should avoid adding them directly to the repo. Alternative option: https://github.com/microsoft/FluidFramework/wiki/Uploading-images-for-the-website-to-Azure-blob-storage

[yann-achard-MS]

For the image files, if possible, we should avoid adding them directly to the repo. Alternative option: https://github.com/microsoft/FluidFramework/wiki/Uploading-images-for-the-website-to-Azure-blob-storage

@Josmithr - is that the recommended approach even for docs that are not part of the website? It seems that the only docs that currently use this approach are from the root docs folder.

[Josmithr]

For the image files, if possible, we should avoid adding them directly to the repo. Alternative option: https://github.com/microsoft/FluidFramework/wiki/Uploading-images-for-the-website-to-Azure-blob-storage

@Josmithr - is that the recommended approach even for docs that are not part of the website? It seems that the only docs that currently use this approach are from the root docs folder.

It is, though we need to do a better job of documenting that (and why). I have an item on my plate for unifying some of the documentation around that. One of the primary objectives is to reduce the number of binary files we check in to the repo.

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

> fluidframework-docs@0.25.0 ci:linkcheck /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test ci:start 1313 linkcheck:full

1: starting server using command "npm run ci:start"
and when url "[ 'http://127.0.0.1:1313' ]" is responding with HTTP status code 200
running tests using command "npm run linkcheck:full"


> fluidframework-docs@0.25.0 ci:start
> http-server ./public --port 1313 --silent


> fluidframework-docs@0.25.0 linkcheck:full
> npm run linkcheck:fast -- --external


> fluidframework-docs@0.25.0 linkcheck:fast
> linkcheck http://localhost:1313 --skip-file skipped-urls.txt --external

Crawling...

Stats:
  443418 links
    3412 destination URLs
       2 URLs ignored
       0 warnings
       0 errors

[alexvy86]

LGTM!