Update readme with common workflows and patterns (#21196)

## Common Workflows and Patterns

This section contains common workflows and patterns to increase inner
dev loop efficiency.

### Build

- `pnpm install` from the root of the repository to install
dependencies. This is necessary for new clones or after pulling changes
from the main branch.
- `pnpm run build:fast` from the root of the repository to perform an
incremental build that matches the CI build process. Incremental builds
tend to leave extra files laying around, so running a clean is sometimes
needed to cleanup ghost tests
- `pnpm run build:fast -- <path>` to build only a specific part of the
repository.
-   `pnpm run build` within a package directory to build that package.
-   `pnpm run build:compile` for cross-package compilation.
-   `pnpm run format` to format the code.

- `fluid-build --vscode` to output error message to work with default
problem matcher in vscode. If `fluid-build` is not installed, please
install it with `npm i -g @fluidframework/build-tools`.

#### Multi package setup

- `fluid-build -t build <NAME_OF_PACKAGES>` to build a multiple
space-separated packages along with all their dependencies. If
`fluid-build` is not installed, please install it with `npm i -g
@fluidframework/build-tools`.

### Debug

- You can also use the VSCode JS debug terminal, then run the test as
normal.

- Sometimes, uncommitted changes can cause build failures. Committing
changes might be necessary to resolve such issues.

### Troubleshooting

-   `pnpm clean` if random build failures, especially with no changes
- `git clean -xdf` to remove extraneous files if debugging becomes slow
or hangs.

## Testing

You can run all of our tests from the root of the repo, or you can run a
scoped set of tests by running the `test`
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
repository, which is required to run all the tests - otherwise some will
be skipped.

First, ensure you have installed [Git LFS](https://git-lfs.com/).
Then, from the repo root:

```shell
git lfs install
git submodule init
git submodule update
```

### Run the tests

Before running the tests, the project has to be built. Depending on what
tests you want to run, execute the following command in the package
directory or at the root:

```shell
npm run test
```

- To run a single test within a module, add `.only` to `it` or
`describe`. To exclude a test, use `.skip`.
- You can use `ts-mocha` to quickly run specific test files without
needing to make the whole project compile. For more details on test
filtering using CLI arguments, refer to the [Mocha
documentation](https://mochajs.org/#command-line-usage).

-   Our test setup generally requires building before running the tests.
- Incremental builds may leave extra files, which can result in ghost
tests. To avoid this, consider running a clean build with the following
command:

```shell
pnpm clean <package>
```

This removes any leftover files from previous builds, providing a clean
testing environment.


[AB#4739](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/4739)
This commit is contained in:
Rishhi Balakrishnan 2024-05-23 13:35:27 -04:00 коммит произвёл GitHub
Родитель c9bc72c5a1
Коммит 7dea35e751
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: B5690EEEBB952194
1 изменённых файлов: 44 добавлений и 0 удалений

Просмотреть файл

@ -167,6 +167,36 @@ There are a few different areas in which we generate documentation content as a
- We leverage [API-Extractor](https://api-extractor.com/) to generate summaries of our package APIs.
This is done as a part of a full build, but it can also be executed in isolation by running `npm run build:api` from the repo root.
## Common Workflows and Patterns
This section contains common workflows and patterns to increase inner dev loop efficiency.
### Build
- `pnpm install` from the root of the repository to install dependencies. This is necessary for new clones or after pulling changes from the main branch.
- `pnpm run build:fast` from the root of the repository to perform an incremental build that matches the CI build process. Incremental builds tend to leave extra files laying around, so running a clean is sometimes needed to cleanup ghost tests
- `pnpm run build:fast -- <path>` to build only a specific part of the repository.
- `pnpm run build` within a package directory to build that package.
- `pnpm run build:compile` for cross-package compilation.
- `pnpm run format` to format the code.
- `fluid-build --vscode` to output error message to work with default problem matcher in vscode. If `fluid-build` is not installed, please install it with `npm i -g @fluidframework/build-tools`.
#### Multi package setup
- `fluid-build -t build <NAME_OF_PACKAGES>` to build a multiple space-separated packages along with all their dependencies. If `fluid-build` is not installed, please install it with `npm i -g @fluidframework/build-tools`.
### Debug
- You can also use the VSCode JS debug terminal, then run the test as normal.
- Sometimes, uncommitted changes can cause build failures. Committing changes might be necessary to resolve such issues.
### Troubleshooting
- `pnpm clean` if random build failures, especially with no changes
- `git clean -xdf` to remove extraneous files if debugging becomes slow or hangs.
## Testing
You can run all of our tests from the root of the repo, or you can run a scoped set of tests by running the `test`
@ -187,10 +217,24 @@ git submodule update
### Run the tests
Before running the tests, the project has to be built. Depending on what tests you want to run, execute the following command in the package directory or at the root:
```shell
npm run test
```
- To run a single test within a module, add `.only` to `it` or `describe`. To exclude a test, use `.skip`.
- You can use `ts-mocha` to quickly run specific test files without needing to make the whole project compile. For more details on test filtering using CLI arguments, refer to the [Mocha documentation](https://mochajs.org/#command-line-usage).
- Our test setup generally requires building before running the tests.
- Incremental builds may leave extra files, which can result in ghost tests. To avoid this, consider running a clean build with the following command:
```shell
pnpm clean <package>
```
This removes any leftover files from previous builds, providing a clean testing environment.
### Include code coverage
```shell