From 9851b8e7a2a74a9a3825ca4996db85f72fc237e2 Mon Sep 17 00:00:00 2001 From: Mark Fields Date: Fri, 15 May 2020 10:06:08 -0700 Subject: [PATCH 1/6] some stub readme's --- components/examples/README.md | 3 +++ components/experimental/README.md | 3 +++ 2 files changed, 6 insertions(+) create mode 100644 components/examples/README.md create mode 100644 components/experimental/README.md diff --git a/components/examples/README.md b/components/examples/README.md new file mode 100644 index 000000000000..f9148aa21499 --- /dev/null +++ b/components/examples/README.md @@ -0,0 +1,3 @@ +# Example Components + +_Coming soon..._ diff --git a/components/experimental/README.md b/components/experimental/README.md new file mode 100644 index 000000000000..1741021919c4 --- /dev/null +++ b/components/experimental/README.md @@ -0,0 +1,3 @@ +# Experimental Components + +_Coming soon..._ From 0b5894e3662c820d11464f9119dc6118f9cf56fc Mon Sep 17 00:00:00 2001 From: Mark Fields Date: Mon, 18 May 2020 09:38:06 -0700 Subject: [PATCH 2/6] Document code structure and add some missing readme's --- README.md | 28 +++++++++++++++++++--- common/build/eslint-config-fluid/README.md | 3 +++ common/lib/common-definitions/README.md | 2 +- common/lib/common-utils/README.md | 3 ++- examples/hosts/electron-host/README.md | 3 +++ examples/hosts/iframe-host/README.md | 3 +++ examples/hosts/literate/README.md | 10 ++++---- packages/README.md | 23 ++++++++++++++++++ server/README.md | 4 +++- tools/README.md | 23 ++++++++++++++++++ 10 files changed, 91 insertions(+), 11 deletions(-) create mode 100644 common/build/eslint-config-fluid/README.md create mode 100644 examples/hosts/electron-host/README.md create mode 100644 examples/hosts/iframe-host/README.md create mode 100644 packages/README.md create mode 100644 tools/README.md diff --git a/README.md b/README.md index 75236d71cb18..e2af5c4e6ea2 100644 --- a/README.md +++ b/README.md @@ -41,9 +41,31 @@ with any additional questions or comments. Get up and running quickly using our documentation at . -## Directory Structure - -_Coming soon._ +## Code Structure + +The core code is built into several large chunks ("minirepos", managed using Lerna) which are versioned separately from one another, but internally all packages in a minirepo are versioned together. And outside the minirepos there are plenty of packages which are versioned independently. + +Here's the breakdown of the repo: + +* Fluid Framework Client Minirepo ([lerna.json](./lerna.json)) + * [Packages](./packages) + * [Example Components](./components/examples) + * [Experimental Components](./components/experimental) + * [Example host](./examples/hosts/iframe-host) +* Reference Service ("Routerlicious") Minirepo ([dir](./server/routerlicious) | [lerna.json](server/routerlicious/lerna.json)) + * [Packages](./server/routerlicious/packages) +* Common Packages + * [Common Definitions](./common/lib/common-definitions) + * [Common Utils](./common/lib/common-utils) +* Internal/Misc Packages + * [Build Common](./common/build/build-common) + * [ESlint Config](./common/build/eslint-config-fluid) + * Other Example Hosts + * [Electron Host](./examples/hosts/electron-host) + * [Literate](./examples/hosts/literate) + * [Docs](./docs) + * [Tools](./tools) + * [Other Server Packages](./server) (excluding [Routerlicious](./server/routerlicious) itself) ## Building diff --git a/common/build/eslint-config-fluid/README.md b/common/build/eslint-config-fluid/README.md new file mode 100644 index 000000000000..4daeb80db7d8 --- /dev/null +++ b/common/build/eslint-config-fluid/README.md @@ -0,0 +1,3 @@ +# ESlint Config + +_Coming soon..._ diff --git a/common/lib/common-definitions/README.md b/common/lib/common-definitions/README.md index f2bc2ca7bedb..b87227365a63 100644 --- a/common/lib/common-definitions/README.md +++ b/common/lib/common-definitions/README.md @@ -1,3 +1,3 @@ # Fluid Common Definitions -Common interfaces and definitions used in Fluid Framework \ No newline at end of file +Common interfaces and definitions used in Fluid Framework diff --git a/common/lib/common-utils/README.md b/common/lib/common-utils/README.md index bfd4ccaa8946..1446f8acc46f 100644 --- a/common/lib/common-utils/README.md +++ b/common/lib/common-utils/README.md @@ -1,2 +1,3 @@ -This package contains code for common utilities used by Fluid Framework +# Fluid Common Utils +Common utilities used by Fluid Framework diff --git a/examples/hosts/electron-host/README.md b/examples/hosts/electron-host/README.md new file mode 100644 index 000000000000..5d0fd3671803 --- /dev/null +++ b/examples/hosts/electron-host/README.md @@ -0,0 +1,3 @@ +# Fluid Example Electron Host + +_Coming soon..._ diff --git a/examples/hosts/iframe-host/README.md b/examples/hosts/iframe-host/README.md new file mode 100644 index 000000000000..c47b67b8f5d3 --- /dev/null +++ b/examples/hosts/iframe-host/README.md @@ -0,0 +1,3 @@ +# Fluid Example IFrame Host + +_Coming soon..._ diff --git a/examples/hosts/literate/README.md b/examples/hosts/literate/README.md index eb963dea563e..0ab92447b1d7 100644 --- a/examples/hosts/literate/README.md +++ b/examples/hosts/literate/README.md @@ -1,5 +1,5 @@ --- -uid: loaders +uid: loaders --- # Literate Fluid Loader @@ -16,7 +16,7 @@ of code. ## Build steps The first (and hardest) step to get up and running is to authenticate against the Fluid private npm feed. To do so -navigate to https://offnet.visualstudio.com/officenet/_packaging?feed=prague&_a=feed, click the "Connect to feed" link, +navigate to , click the "Connect to feed" link, choose "npm" and then follow the instructions. Once you've done that getting up and running is simple. @@ -26,11 +26,11 @@ npm install npm start ``` -Then navigate to http://localhost:8080. This will redirect you to http://localhost:8080/example but you can change +Then navigate to This will redirect you to but you can change 'example' to any string you'd like and a new document will be created under that name. By default a new Flow View will be created but by specifying the chaincode query parameter any of the packages on -https://packages.wu2.prague.office-int.com can be loaded - i.e. -http://localhost:8080/new-document?chaincode=@chaincode/tourofheroes@0.0.5918. + can be loaded - i.e. + ## The Code diff --git a/packages/README.md b/packages/README.md new file mode 100644 index 000000000000..41f9ccc9aa65 --- /dev/null +++ b/packages/README.md @@ -0,0 +1,23 @@ +# Fluid Framework Client Core Packages + +_Details coming soon..._ + +[agents](./agents) ... + +[drivers](./drivers) ... + +[framework](./framework) ... + +[hosts](./hosts) ... + +[loader](./loader) ... + +[runtime](./runtime) ... + +[server](./server) ... + +[test](./test) ... + +[tools](./tools) ... + +[utils](./utils) ... diff --git a/server/README.md b/server/README.md index a393f6f5d293..9400253e1ef2 100644 --- a/server/README.md +++ b/server/README.md @@ -8,6 +8,8 @@ This directory contains our reference server implementation. [Routerlicious](./r [Charts](./charts) Kubernetes charts for the micro-services +[Gateway](./gateway) Internal landing page for Fluid, hosts Waterpark + [Gitrest](./gitrest) provides a REST API to a GitHub repository. It's API is based off of GitHub's REST APIs. [Gitssh](./gitssh) is a git ssh server client container. @@ -20,7 +22,7 @@ This directory contains our reference server implementation. [Routerlicious](./r [Routerlicious](./routerlicious) composed reference server implementation -[Service](./service) Experimental routerlicious with faster throughput +[Tinylicious](./tinylicious) Light-weight monolithic server implementation ## Build Status diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 000000000000..4ec0fcd570c3 --- /dev/null +++ b/tools/README.md @@ -0,0 +1,23 @@ +# Fluid Framework Tools Dir + +_Details coming soon..._ + +[build-server-resources](./build-server-resources) ... + +[fluid-build-tools](./fluid-build-tools) ... + +[fluid-metrics](./fluid-metrics) ... + +[fluidpreview-intercept](./fluidpreview-intercept) ... + +[generator-fluid](./generator-fluid) Yo generator for creating a new Fluid Component + +[getkeys](./getkeys) ... + +[headless-chrome](./headless-chrome) ... + +[logger](./logger) ... + +[repo-policy-check](./repo-policy-check) ... + +[search-content-extractor](./search-content-extractor) ... From 7ef16790fb4b7d0a1b42168745b700b860bc9490 Mon Sep 17 00:00:00 2001 From: Mark Fields Date: Mon, 18 May 2020 14:29:49 -0700 Subject: [PATCH 3/6] PR feedback/follow up --- README.md | 33 ++++++++++++++++++--------------- server/auspkn/README.md | 2 +- server/headless-agent/README.md | 2 +- 3 files changed, 20 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index e2af5c4e6ea2..aed7b7a0ecec 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,17 @@ so you can focus on your app's business logic. Fluid's data synchronization is f bandwidth. Fluid is extensible, too. You can write components which can be re-used or you can even create new distributed data structures. -## Installing +## Getting started using the Fluid Framework -_Coming soon._ +You may be here because you want to... + +- Build a Component +- Build a Container +- Host Fluid containers in your application +- Develop a new DDS +- Implement a Fluid server + +All of these are documented at . ## Contributing @@ -37,10 +45,6 @@ with any additional questions or comments. * Help each other in the [Fluid Community Discord]() **(community channel not yet created)** * Join the discussion on Twitter **(hashtag not established yet)** -## Documentation - -Get up and running quickly using our documentation at . - ## Code Structure The core code is built into several large chunks ("minirepos", managed using Lerna) which are versioned separately from one another, but internally all packages in a minirepo are versioned together. And outside the minirepos there are plenty of packages which are versioned independently. @@ -52,11 +56,13 @@ Here's the breakdown of the repo: * [Example Components](./components/examples) * [Experimental Components](./components/experimental) * [Example host](./examples/hosts/iframe-host) -* Reference Service ("Routerlicious") Minirepo ([dir](./server/routerlicious) | [lerna.json](server/routerlicious/lerna.json)) +* Reference Fluid Ordering Service ("Routerlicious") Minirepo ([dir](./server/routerlicious) | [lerna.json](server/routerlicious/lerna.json)) * [Packages](./server/routerlicious/packages) * Common Packages * [Common Definitions](./common/lib/common-definitions) * [Common Utils](./common/lib/common-utils) +* Auxiliary Microservices supporting Routerlicious + * [Server dir](./server) (excluding [Routerlicious](./server/routerlicious) itself) * Internal/Misc Packages * [Build Common](./common/build/build-common) * [ESlint Config](./common/build/eslint-config-fluid) @@ -65,7 +71,6 @@ Here's the breakdown of the repo: * [Literate](./examples/hosts/literate) * [Docs](./docs) * [Tools](./tools) - * [Other Server Packages](./server) (excluding [Routerlicious](./server/routerlicious) itself) ## Building @@ -89,8 +94,6 @@ npm run build:fast ## Testing -### Running the tests - You can run the tests from root to run all tests (via lerna), or you can run a scoped set of tests by running the command from the directory you're interested in. > Note: Some of the tests depend on test collateral that lives in a submodule here: . You may choose to fetch that collateral into your local repository, which is required to run all the tests - otherwise some will be skipped. First install git LFS from . Then, from the repo root: @@ -102,19 +105,19 @@ You can run the tests from root to run all tests (via lerna), or you can run a s > ``` > -#### Run the tests +### Run the tests ```bash npm run test ``` -#### Include code coverage +### Include code coverage ```bash npm run test:coverage ``` -#### Mimic the official CI build +### Mimic the official CI build _Note: The official build uses npm run test:full, which doesn’t work on windows._ @@ -123,11 +126,11 @@ npm run test:coverage npm run test:copyresults ``` -#### Run tests from within VS Code +### Run tests from within VS Code We've checked in [VS Code configuration](https://github.com/microsoft/FluidFramework/blob/master/.vscode/launch.json) enabling F5 from a `spec.ts` file to run those tests, if you set the debug configuration to "Debug Current Test". -## Try it out locally +## Run it out locally ### Single browser window, two panes diff --git a/server/auspkn/README.md b/server/auspkn/README.md index cb9abe109ee5..2ca29173106b 100644 --- a/server/auspkn/README.md +++ b/server/auspkn/README.md @@ -2,4 +2,4 @@ # Auspkn -Provides REST API access to npm packages \ No newline at end of file +Provides REST API access to npm packages, targeting the internal Azure DevOps feed endpoint today. diff --git a/server/headless-agent/README.md b/server/headless-agent/README.md index 2cc7e46be48f..c28808ee0ee4 100644 --- a/server/headless-agent/README.md +++ b/server/headless-agent/README.md @@ -3,7 +3,7 @@ To begin you'll need to connect to the Fluid private npm repository. Instructions can be found [here](../routerlicious/README.md#authorizing-to-private-npm-feed) # Headless Agent -Loads Fluid components on a headless chromium browser. +Loads Fluid components on a headless chromium browser, as opposed to the Node.js runtime. To build ``` From 5333d8b44f12e86ddce35842b45c9b5ba27603ae Mon Sep 17 00:00:00 2001 From: Mark Fields Date: Mon, 18 May 2020 14:41:45 -0700 Subject: [PATCH 4/6] PR feedback --- README.md | 2 +- common/build/eslint-config-fluid/README.md | 2 +- common/lib/common-definitions/README.md | 2 +- common/lib/common-utils/README.md | 2 +- examples/hosts/electron-host/README.md | 2 +- examples/hosts/iframe-host/README.md | 2 +- examples/hosts/literate/README.md | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index aed7b7a0ecec..ab40f36ed77b 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ with any additional questions or comments. ## Code Structure -The core code is built into several large chunks ("minirepos", managed using Lerna) which are versioned separately from one another, but internally all packages in a minirepo are versioned together. And outside the minirepos there are plenty of packages which are versioned independently. +The core code is built into several large chunks ("minirepos", managed using [Lerna](https://lerna.js.org/)) which are versioned separately from one another, but internally all packages in a minirepo are versioned together. And outside the minirepos there are plenty of packages which are versioned independently. Here's the breakdown of the repo: diff --git a/common/build/eslint-config-fluid/README.md b/common/build/eslint-config-fluid/README.md index 4daeb80db7d8..9749de7f6fbe 100644 --- a/common/build/eslint-config-fluid/README.md +++ b/common/build/eslint-config-fluid/README.md @@ -1,3 +1,3 @@ -# ESlint Config +# @microsoft/eslint-config-fluid _Coming soon..._ diff --git a/common/lib/common-definitions/README.md b/common/lib/common-definitions/README.md index b87227365a63..bdd641902748 100644 --- a/common/lib/common-definitions/README.md +++ b/common/lib/common-definitions/README.md @@ -1,3 +1,3 @@ -# Fluid Common Definitions +# @microsoft/fluid-common-definitions Common interfaces and definitions used in Fluid Framework diff --git a/common/lib/common-utils/README.md b/common/lib/common-utils/README.md index 1446f8acc46f..f0caf52fc64d 100644 --- a/common/lib/common-utils/README.md +++ b/common/lib/common-utils/README.md @@ -1,3 +1,3 @@ -# Fluid Common Utils +# @microsoft/fluid-common-utils Common utilities used by Fluid Framework diff --git a/examples/hosts/electron-host/README.md b/examples/hosts/electron-host/README.md index 5d0fd3671803..5bef588cb703 100644 --- a/examples/hosts/electron-host/README.md +++ b/examples/hosts/electron-host/README.md @@ -1,3 +1,3 @@ -# Fluid Example Electron Host +# @prague/electron-host _Coming soon..._ diff --git a/examples/hosts/iframe-host/README.md b/examples/hosts/iframe-host/README.md index c47b67b8f5d3..34615b25299f 100644 --- a/examples/hosts/iframe-host/README.md +++ b/examples/hosts/iframe-host/README.md @@ -1,3 +1,3 @@ -# Fluid Example IFrame Host +# @fluid-example/iframe-host _Coming soon..._ diff --git a/examples/hosts/literate/README.md b/examples/hosts/literate/README.md index 0ab92447b1d7..8d318204df5d 100644 --- a/examples/hosts/literate/README.md +++ b/examples/hosts/literate/README.md @@ -1,5 +1,5 @@ --- -uid: loaders +uid: loaders --- # Literate Fluid Loader From a8a41ef5e5e5822d732d03672c5e0530e8829e58 Mon Sep 17 00:00:00 2001 From: Mark Fields Date: Mon, 18 May 2020 14:57:25 -0700 Subject: [PATCH 5/6] eslint-config-fluid readme --- common/build/eslint-config-fluid/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common/build/eslint-config-fluid/README.md b/common/build/eslint-config-fluid/README.md index 9749de7f6fbe..3f929dfec636 100644 --- a/common/build/eslint-config-fluid/README.md +++ b/common/build/eslint-config-fluid/README.md @@ -1,3 +1,3 @@ # @microsoft/eslint-config-fluid -_Coming soon..._ +A shared ESLint config used by all the Fluid Framework packages From 5a54f34d0a3d806533636fbc2ec457ecc1289e67 Mon Sep 17 00:00:00 2001 From: Mark Fields Date: Wed, 20 May 2020 09:17:16 -0700 Subject: [PATCH 6/6] Typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ab40f36ed77b..20698c512dde 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ npm run test:copyresults We've checked in [VS Code configuration](https://github.com/microsoft/FluidFramework/blob/master/.vscode/launch.json) enabling F5 from a `spec.ts` file to run those tests, if you set the debug configuration to "Debug Current Test". -## Run it out locally +## Run it locally ### Single browser window, two panes