Update "Code structure" in readme (#10824)
Co-authored-by: Craig Macomber <Craig.Macomber@microsoft.com> Co-authored-by: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com>
This commit is contained in:
Craig Macomber (Microsoft)
GitHub
Родитель
adbc462be6
Коммит
b08ddf3586
92
README.md
92
README.md
|
|
@ -7,8 +7,8 @@ applications using JavaScript or TypeScript.
|
|||
|
||||
You may be here because you want to...
|
||||
|
||||
* Learn more about the Fluid Framework
|
||||
* Build a Fluid object
|
||||
- Learn more about the Fluid Framework
|
||||
- Build a Fluid object
|
||||
|
||||
Documentation and guides can be found at <https://fluidframework.com/>.
|
||||
|
||||
|
|
@ -22,36 +22,46 @@ Have questions? Engage with other Fluid Framework users and developers in the [D
|
|||
|
||||
The core code for both the Fluid client packages _and_ the reference ordering service is contained within this repo.
|
||||
|
||||
The repo structure is somewhat unique because it contains two monorepos as well as several standalone packages. The
|
||||
The repo structure is somewhat unique because it contains five monorepos as well as several standalone packages. The
|
||||
monorepos are managed using [Lerna](https://lerna.js.org/) and are versioned separately from one another, but internally
|
||||
all packages in a monorepo are versioned together. Outside the monorepos there are plenty of packages which are
|
||||
versioned independently.
|
||||
|
||||
Here's the breakdown of the repo:
|
||||
These monorepos (which also serve as "release groups") do not necessary align with package namespaces,
|
||||
and also don't necessary correspond to a single directory of this repo.
|
||||
|
||||
* Fluid Framework Client Monorepo ([lerna.json](./lerna.json))
|
||||
* [Packages](./packages)
|
||||
* [Fluid Examples](./examples)
|
||||
* Azure-related Monorepo ([dir](./azure) | [lerna.json](azure/lerna.json)
|
||||
* [Packages](./azure/packages)
|
||||
* Reference Fluid Ordering Service ("Routerlicious") Monorepo ([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 Microservice Packages (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)
|
||||
* [Docs](./docs)
|
||||
* [Tools](./tools)
|
||||
Here's the list of Lerna managed release groups:
|
||||
|
||||
- core (previously known as "Fluid Framework Client" or "Client") (Rooted in [./](./). Configured by [./lerna.json](./lerna.json))
|
||||
- [./packages](./packages) (Published in the `@fluidframework/` namespace, but some in `@fluid-tools` and unpublished packages in `@fluid-internal/`)
|
||||
- [./experimental](./experimental) (Published in the `@fluid-experimental/` namespace)
|
||||
- [./examples](./examples) (Not published, live in the `@fluid-example/` namespace)
|
||||
- azure (Rooted in [./azure](./azure). Configured by [azure/lerna.json](azure/lerna.json))
|
||||
- [Packages](./azure/packages) (Published in the `@fluidframework/` namespace)
|
||||
- routerlicious (Reference Fluid Ordering Service) (Rooted in [./server/routerlicious](./server/routerlicious). Configured by [./server/routerlicious/lerna.json](server/routerlicious/lerna.json))
|
||||
- [Packages](./server/routerlicious/packages) (Published in the `@fluidframework/` namespace)
|
||||
- gitrest (Rooted in [./server/gitrest](./server/gitrest). Configured by [./server/gitrest/lerna.json](./server/gitrest/lerna.json))
|
||||
- [Packages](./server/gitrest/packages) (Published in the `@fluidframework/` namespace)
|
||||
- historian (Rooted in [./server/historian](./server/historian). Configured by [./server/historian/lerna.json](./server/historian/lerna.json))
|
||||
- [Packages](./server/historian/packages) (Published in the `@fluidframework/` namespace)
|
||||
|
||||
Here's a list of other sets of other packages (each package within these groups is versioned independently,
|
||||
forming its own release group):
|
||||
|
||||
- "Common" Packages: miscellaneous packages in the [./common](./common) directory and published under the `@fluidframework/` namespace. Most of these (but not all) have "common" in their package name.
|
||||
Packages which are used by multiple other groups of packages (such as built tools, linter configs and protocol definitions) live here.
|
||||
- "Tools" Packages: miscellaneous packages in the [./tools](./tools) directory and published under a variety of namespaces.
|
||||
Logically about the same as "Common", but most of the names include "tools" instead of "common".
|
||||
- Auxiliary Microservice Packages (supporting Routerlicious)
|
||||
- [./server](./server) excluding routerlicious, gitrest and historian (Published in the `@fluidframework/` namespace)
|
||||
- [./docs](./docs): The code and content for <https://fluidframework.com>.
|
||||
|
||||
Dependencies between packages in various layers of the system are enforced via a build step called
|
||||
[layer-check](./tools/build-tools/src/layerCheck). You can view the full list of packages and layers in
|
||||
[docs/PACKAGES.md](./docs/PACKAGES.md).
|
||||
|
||||
## Building
|
||||
|
||||
In order to build the Fluid Framework, ensure that you have installed [Git](https://git-scm.com/downloads) and the version of
|
||||
[Node.js](https://nodejs.org/) noted in the [.nvmrc file](https://raw.githubusercontent.com/microsoft/FluidFramework/main/.nvmrc).
|
||||
|
||||
|
|
@ -77,13 +87,13 @@ See also: [Contributing](#Contributing)
|
|||
|
||||
### Other Build Requirements
|
||||
|
||||
- Building [server/Routerlicious](./server/routerlicious/README.md)
|
||||
- Refer to that package's README for additional requirements.
|
||||
- Note that these requirements do not affect all workflows (e.g. the one noted [above](#building)), but will affect workflows that include the packages under `server` (e.g. `fluid-build --symlink:full`).
|
||||
- Building [server/Routerlicious](./server/routerlicious/README.md)
|
||||
- Refer to that package's README for additional requirements.
|
||||
- Note that these requirements do not affect all workflows (e.g. the one noted [above](#building)), but will affect workflows that include the packages under `server` (e.g. `fluid-build --symlink:full`).
|
||||
|
||||
#### On Windows
|
||||
|
||||
- Ensure that you have enabled running Powershell scripts by setting your environment's [Execution Policy](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7.2).
|
||||
- Ensure that you have enabled running Powershell scripts by setting your environment's [Execution Policy](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7.2).
|
||||
|
||||
## Testing
|
||||
|
||||
|
|
@ -91,7 +101,7 @@ You can run all of our tests from the root of the repo, or you can run a scoped
|
|||
command from the package you're interested in.
|
||||
|
||||
Note: Some of the tests depend on test collateral that lives in a submodule here:
|
||||
<https://github.com/microsoft/FluidFrameworkTestData>. You may choose to fetch that collateral into your local
|
||||
<https://github.com/microsoft/FluidFrameworkTestData>. 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 <https://git-lfs.github.com/>. Then, from the repo root:
|
||||
|
|
@ -119,10 +129,10 @@ npm run test:coverage
|
|||
Our CI pipelines run on Linux machines, and the npm scripts all have the `ci` prefix.
|
||||
To replicate the test steps from the CI pipeline locally, run the following commands for the packages or Lerna monorepos:
|
||||
|
||||
Run | Non-Windows | Windows |
|
||||
---------|----------------------------|-------------------------------------------------------|
|
||||
PR | `npm run ci:test` | `npm run test:report && npm run test:copyresults` |
|
||||
Official | `npm run ci:test:coverage` | `npm run test:coverage && npm run test:copyresults` |
|
||||
| Run | Non-Windows | Windows |
|
||||
| -------- | -------------------------- | --------------------------------------------------- |
|
||||
| PR | `npm run ci:test` | `npm run test:report && npm run test:copyresults` |
|
||||
| Official | `npm run ci:test:coverage` | `npm run test:coverage && npm run test:copyresults` |
|
||||
|
||||
### Run tests from within VS Code
|
||||
|
||||
|
|
@ -135,10 +145,10 @@ enabling F5 from a `spec.ts` file to run those tests if you set the debug config
|
|||
|
||||
_This will use an in-memory implementation of the Fluid server to sync between the two panes in the browser window._
|
||||
|
||||
* Choose an example under `/examples`
|
||||
* Navigate to the example's directory, e.g. `/examples/data-objects/clicker`
|
||||
* `npm run start`
|
||||
* Browse to <http://localhost:8080> to interact with two copies of the example side-by-side
|
||||
- Choose an example under `/examples`
|
||||
- Navigate to the example's directory, e.g. `/examples/data-objects/clicker`
|
||||
- `npm run start`
|
||||
- Browse to <http://localhost:8080> to interact with two copies of the example side-by-side
|
||||
|
||||
### Multiple browser instances on the same device
|
||||
|
||||
|
|
@ -155,18 +165,18 @@ npm run start
|
|||
|
||||
Then:
|
||||
|
||||
* Navigate to the example of your choice (same as above)
|
||||
* `npm run start:tinylicious`
|
||||
* Browse to <http://localhost:8080,> copy the full URL you're redirected to, and open in a second window to collaborate
|
||||
- Navigate to the example of your choice (same as above)
|
||||
- `npm run start:tinylicious`
|
||||
- Browse to <http://localhost:8080,> copy the full URL you're redirected to, and open in a second window to collaborate
|
||||
|
||||
## Contributing
|
||||
|
||||
There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid.
|
||||
|
||||
* Participate in Q&A in our [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
|
||||
* [Submit bugs](https://github.com/microsoft/FluidFramework/issues) and help us verify fixes as they are checked in.
|
||||
* Review the [source code changes](https://github.com/microsoft/FluidFramework/pulls).
|
||||
* [Contribute bug fixes](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md).
|
||||
- Participate in Q&A in our [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
|
||||
- [Submit bugs](https://github.com/microsoft/FluidFramework/issues) and help us verify fixes as they are checked in.
|
||||
- Review the [source code changes](https://github.com/microsoft/FluidFramework/pulls).
|
||||
- [Contribute bug fixes](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md).
|
||||
|
||||
Detailed instructions for working in the repo can be found in the
|
||||
[Wiki](https://github.com/microsoft/FluidFramework/wiki).
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче