docs: add Concepts documentation tree (testing + summarization branches) by agarwal-navin · Pull Request #27523 · microsoft/FluidFramework

agarwal-navin · 2026-06-09T18:18:23Z

Description

Introduces a tree-style engineering documentation structure for the repo. A new root-level CONCEPTS.md acts as a single, navigable entry point that gives a high-level tour of how the framework works and links out to deeper docs that live next to the code they describe.

Each package can in turn have its own CONCEPTS.md doc if it chooses to do so. For example, tree DDS has a lot of interesting concepts some with docs and some without - it can tie it all with this style.

Another advantage of this is it helps agents find information easily.

CONCEPTS.md covers, at a glance. These are just the initial set of concepts to show as examples - More will be added in the future.

Programming models — encapsulated vs. declarative
Layers — the four layers (Driver / Loader / Runtime / Datastore) and how the container runtime, data store runtime, and DDSes nest within them
Compatibility — API, layer, cross-client, and data-at-rest
Op processing, Summarization, and Garbage collection — linking to the existing module READMEs under container-runtime
Testing

This PR fully wires in the first two branches as worked examples:

Testing — new TESTING.md is the cross-cutting hub. It makes explicit that tests live in two places: per-package unit/fuzz tests under each package's src/test, and the cross-cutting suites (e2e, compat, snapshot, load) under packages/test. A new packages/test/README.md describes that directory's shared/cross-cutting test infrastructure.
Summarization — wired through the existing, high-quality container-runtime/src/summary/README.md rather than duplicating it.

The root README.md gets a callout near the top linking to CONCEPTS.md so the tree is discoverable from the repo landing page.

Docs-only change: no code, public API, or package behavior is affected.

This is an initial proposal for the documentation style — feedback welcome on:

The overall tree shape and section ordering in CONCEPTS.md.
The split between root-level overview docs vs. docs that live next to code.
Which branches to flesh out next (op processing and GC already have module READMEs ready to wire deeper; Layers could use a dedicated overview doc).

Marking as draft while the style is being discussed.

Introduce CONCEPTS.md as a root entry point that gives a high-level tour of the framework (programming models, the four layers, compatibility, op processing, summarization, garbage collection, testing) and links into the code where each concept lives. - Add TESTING.md as the cross-cutting testing hub (unit/fuzz live per-package; e2e/compat/snapshot/load live in packages/test). - Add packages/test/README.md describing that directory's shared/cross-cutting test infrastructure. - Link CONCEPTS.md from the top of the root README so it's discoverable. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

github-actions · 2026-06-09T18:19:29Z

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (292 lines, 4 files), I've queued these reviewers:

Correctness — logic errors, race conditions, lifecycle issues
Security — vulnerabilities, secret exposure, injection
API Compatibility — breaking changes, release tags, type design
Performance — algorithmic regressions, memory leaks
Testing — coverage gaps, hollow tests

How this works

Adjust the reviewer set by ticking/unticking boxes above. Reviewer toggles alone don't trigger anything.
Tick Start review below to dispatch the review fleet.
After review finishes, tick Start review again to request another run — it auto-resets after each dispatch.
This comment updates as new commits land; your reviewer selections are preserved.
Start review

alexvy86

The testing part might want some mention of packages/service-clients/end-to-end-tests, and maybe about the fact that examples/ has several packages with a pattern where tests/ lives next to src/ instead of inside it.

alexvy86 · 2026-06-09T18:58:32Z

+- Add `.only` / `.skip` to focus or exclude individual tests; some tests need the Git LFS
+  submodule (`FluidFrameworkTestData`) fetched.


They seem like separate concerns to me.

Suggested change

- Add `.only` / `.skip` to focus or exclude individual tests; some tests need the Git LFS

submodule (`FluidFrameworkTestData`) fetched.

- Add `.only` / `.skip` to focus or exclude individual tests.

- Snapshot tests need the Git LFS submodule (`FluidFrameworkTestData`) fetched.

Josmithr · 2026-06-09T22:42:12Z

@@ -0,0 +1,74 @@
+# Testing


We also have a DEV.md file at the root that has instructions for various things like running tests in the repo. It might be worth adding a link to this from there if/where appropriate.

github-actions · 2026-06-09T22:49:48Z

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> [email protected] ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> [email protected] serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> [email protected] check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  290922 links
    1934 destination URLs
    2184 URLs ignored
       0 warnings
       0 errors

Josmithr · 2026-06-09T23:22:53Z

+
+| Package | What it is |
+| ------- | ---------- |
+| [`test-end-to-end-tests`](./test-end-to-end-tests/README.md) | The main e2e suite: a real container loop, parameterized over drivers and version combinations. |


Nit (since we haven't used the abbreviation "e2e" yet in the document):

Suggested change

| [`test-end-to-end-tests`](./test-end-to-end-tests/README.md) | The main e2e suite: a real container loop, parameterized over drivers and version combinations. |

| [`test-end-to-end-tests`](./test-end-to-end-tests/README.md) | The main end-to-end (e2e) suite: a real container loop, parameterized over drivers and version combinations. |

Josmithr · 2026-06-09T23:23:55Z

+| [`test-end-to-end-tests`](./test-end-to-end-tests/README.md) | The main e2e suite: a real container loop, parameterized over drivers and version combinations. |
+| [`snapshots`](./snapshots/README.md) | Validates that current code can load older snapshots/summaries (corpus partly in the `FluidFrameworkTestData` submodule). |
+| [`test-service-load`](./test-service-load/README.md) | Load/stress tool: many simulated clients and high op rates against a real or local service. |
+| [`local-server-tests`](./local-server-tests/) | Scenarios that need direct local‑server control (disconnect/nack). |


Nit

Suggested change

| [`local-server-tests`](./local-server-tests/) | Scenarios that need direct local‑server control (disconnect/nack). |

| [`local-server-tests`](./local-server-tests/) | Scenarios that need direct local‑server control (e.g. disconnect/nack). |

Josmithr · 2026-06-09T23:43:27Z

+- **Declarative model** — you describe a fixed schema of shared objects up front (e.g. via
+  `SharedTree` / the `fluid-framework` container schema) and the framework wires it up. Simpler
+  to consume; the shape is known at build time.


I don't think the SharedTree schema is relevant to the point here. I think just the container schema is relevant in this context.

Josmithr · 2026-06-10T00:10:17Z

+  infrastructure that don't belong to any one package (end‑to‑end, cross‑version/compat, drivers,
+  snapshots, load).
+
+## Test styles at a glance


We also have performance benchmarks. I don't know what guidance we have documented for this, but would be worth calling out (we could always leave TODOs where links should be to indicate documentation that still needs to be written).

Josmithr · 2026-06-10T00:11:20Z

+| **Snapshot compatibility** | New code can still load summaries/snapshots written by old code. | [`packages/test/snapshots`](./packages/test/snapshots/README.md) |
+| **Load / stress** | Behavior under many clients and high op rates. | [`packages/test/test-service-load`](./packages/test/test-service-load/README.md), [`local-server-stress-tests`](./packages/test/local-server-stress-tests/) |
+
+## Tests that live in each package


I think the SharedTree package has some in-package testing best practices documentation as well that we may or may not want to hoist up to this level.

(Not necessarily for this PR)

alexvy86 reviewed Jun 9, 2026

View reviewed changes

Josmithr reviewed Jun 9, 2026

View reviewed changes

Josmithr reviewed Jun 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add Concepts documentation tree (testing + summarization branches)#27523

docs: add Concepts documentation tree (testing + summarization branches)#27523
agarwal-navin wants to merge 1 commit into
microsoft:mainfrom
agarwal-navin:ffDocs

agarwal-navin commented Jun 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

alexvy86 left a comment

Uh oh!

alexvy86 Jun 9, 2026

Uh oh!

Josmithr Jun 9, 2026

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

Josmithr Jun 9, 2026

Uh oh!

Josmithr Jun 9, 2026

Uh oh!

Josmithr Jun 9, 2026

Uh oh!

Josmithr Jun 10, 2026

Uh oh!

Josmithr Jun 10, 2026

Uh oh!

Josmithr Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		- Add `.only` / `.skip` to focus or exclude individual tests; some tests need the Git LFS
		submodule (`FluidFrameworkTestData`) fetched.

	\| [`test-end-to-end-tests`](./test-end-to-end-tests/README.md) \| The main e2e suite: a real container loop, parameterized over drivers and version combinations. \|
	\| [`test-end-to-end-tests`](./test-end-to-end-tests/README.md) \| The main end-to-end (e2e) suite: a real container loop, parameterized over drivers and version combinations. \|

	\| [`local-server-tests`](./local-server-tests/) \| Scenarios that need direct local‑server control (disconnect/nack). \|
	\| [`local-server-tests`](./local-server-tests/) \| Scenarios that need direct local‑server control (e.g. disconnect/nack). \|

Conversation

agarwal-navin commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

alexvy86 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 9, 2026

linkcheck output

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

agarwal-navin commented Jun 9, 2026 •

edited

Loading