See the updates in `markdown-magic/README` for the full list of renames.
Also note that in addition to the rename from `EXAMPLE_PACKAGE_README`
TO `EXAMPLE_README_HEADER`, that template was updated to _only_ include
"header" contents (for now, this is just the "Getting Started" section).
It now omits the "footer" contents which are now available via the
renamed `README_FOOTER` template. There were no existing usages of this
updated template outside of tests, so no usages had to be updated. I
will likely update many of our examples to use this updated template in
a follow-up PR.
## 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)
Adds notes to the package README, and fills in missing source code
comment.
Also fills in some gaps in our larger repo workflow documentation in the root README.
All the current READMEs reference the internal version format which is
no longer supported. I updated the template and regenerated the files.
Once merged, this will be cherry-picked to the RC1 release branch.
AB#6738
Update `fluid-build`'s README.md:
- Removing legacy information
- Add more examples for task and package selection
- Describe the task and dependency definition system
- Update how incremental is detected.
- Describe experimental worker mode
- Describe where to fine the specification for release groups.
Also:
- Update spacing on command line help
- Update some comment to make it easier to read.
No template changes were made. I simply ran `npm run build` from the
docs directory, and these were the resulting changes.
The only other change here was moving some contents that had been
incorrectly added to an auto-generated content region outside of that
region so it will not be blown away in the future.
Adds infrastructure for running image-based visual regression tests for
our devtools view components. Also adds a couple of initial sample
tests.
Instructions for how to use these have been added to the README.
Every test
[story](https://storybook.js.org/docs/react/writing-stories/introduction)
is run in all 3 of our supported themes, to ensure our styling works as
expected (and to ensure our high-contrast support is working correctly).
Other changes:
* Updates devtools-view to build as ESM instead of CommonJS
* The `@previewjs` libraries are ESM only - this seemed the easiest path
forward for resolving that issue. And since the devtools-view package is
not publicly available, we don't have any CommonJS compatibility
requirements for it.
---------
Co-authored-by: Alex Villarreal <716334+alexvy86@users.noreply.github.com>
## Description
Move general install and build instructions out of the Mac specific
section.
Remove use of lerna in descriptions of release groups as it is no longer
accurate.
Update list of release groups to account for changes with azure.
Now that we are using `~` interdependencies within the repo, we want to
make sure that customers know that they should continue to use `^`
dependencies when depending on Fluid Framework packages. This PR adds a
new markdown-magic script and updates READMEs across the client release
group accordingly.
BREAKING CHANGE: This is technically a breaking change since the default
output for some functions changed.
I've updated the build-tools release group pipeline to use `~`
interdependency ranges by default. It's overridable at build-time in the
ADO UI.
I also moved the "update package versions" inline script into a file
because it ensures that _any_ non-0 exit code from within the script
causes the step to fail. This will make debugging easier by causing a
failure in the actual step that failed.
Does not change when / where the tooling is invoked, it simply hoists
the underlying logic into its own tooling library.
Subsequent changes will update the patterns for when / where we invoke
the tooling to better encapsulate doc generation in different parts of
the repo.
Notes:
* Abstracting the logic required updating how `INCLUDE` pragma paths are
represented. Previously, these were all written relative to the repo
root. Now they are relative to the document containing the pragma.
* Since the home of the logic changes, the generated content notices
added to documents was updated.
* A few pragma names were changed to make the usage semantics a bit more
explicit.
* The default value of `usesTinylious` for "Getting Started" sections
was changed from `false` to `true`, as the majority of our uses specify
true.
All of the changes to documentation files should be due to one of the
above - no other functional / content changes are expected.
---------
Co-authored-by: Tyler Butler <tyler@tylerbutler.com>
Co-authored-by: Alex Villarreal <716334+alexvy86@users.noreply.github.com>
This change adds a `format:changed` script to the root package.json that
uses [pretty-quick](https://github.com/azz/pretty-quick) to run prettier
only on changed files. pretty-quick supports a `--branch` argument that
I set to `main` for the default, but there is also a
`format:changed:next` script to run against next.
This change adds devDependencies on the mocha and jest testing tools to
the root package.json in the repo. This is to enable easier test running
and debugging using VSCode. However, this makes it possible for projects
to have a 'phantom dependency' on
these tools, so I added a dev note to the readme describing why the root
deps are there and warns about phantom deps.
CI runs have a step that sets the version of packages, which edits the
package.json and changes the whitespace formatting. We have a couple of
different ways we set versions, so the quickest fix seemed to be to add
steps to the "set package version" workflow that:
1. Runs a prettier check on just the package.json files in the release
group BEFORE setting versions.
2. Runs a prettier format on just the package.json files in the release
group AFTER setting versions.
Step 1 is needed because otherwise, badly formatted package.json files
would go undetected, because we force them to be formatted in CI in step
2. The no extraneous files check already ignores package.json files
because they change when the package version changes, so we can't rely
on it as a backstop; we need to check them elsewhere in the pipeline.
An alternative to this workaround is to update our pipelines to use flub
to set versions, and update flub to not touch whitespace. That will take
more time, and this approach seems sufficient.
I also opportunistically updated the scripts and config for the
benchmark project since it was outdated, and I updated the scripts for
the release groups so that they lint and format the files in the root of
the release group. And I updated the .prettierignore file as needed to
exclude stuff.
Finally, there were some examples and PropertyDDS projects that did not
have a config file, so I added one and formatted all the code.
This is a companion PR to #13554. This PR contains only documentation
updates to reflect that we use pnpm for package management in the client
release group (after the other PR is merged). I split it out to make the
PRs easier to review.
Intended to prevent contention between our generated documentation
contents and prettier's formatting opinions.
Note the change to common/build/eslint-config-fluid/README.md where
prettier had previously re-formatted its generated script contents.
Updates our markdown-magic logic in the following ways:
- Simplifies code with new helper functionality
- Extracts basic templates into md files
- Ensures the generated content disclaimer is included in all gen'd doc
sections
Also updates the contribution guidelines template to match the content
in the repo README, and updates that README to use md-magic.
The primary changes to review are:
- `./docs/md-magic-config.js`
- the new md files under `./md-magic-templates`
The remaining changes are all generated using md-magic.
Moves build-tools and build-cli into a new release group. This will make it easier to modify the build tools and CLI in lockstep. The packages were moved using git mv.
Moves the azure-client, azure-service-utils, and the app-integration-external-controller example to a new lerna monorepo in azure/. This enables us to version and release the Azure-related packages separately from the core platform packages.
CI npm script should have ci:*.
Since our CI are running on linux, updated instruction on how to replicate it and give different instruction for windows in the README.md. (and note that the instruction is just different for windows, not that it doesn't support windows)
Joshua Smithrud
Rishhi Balakrishnan
Tyler Butler
Ji Kim
Curtis Man
Craig Macomber (Microsoft)
justus-camp
Tyler Butler
Sam Broner
Daniel Lehenbauer
Skyler Jokiel
Tony Murphy
Micah Godbolt
Mark Fields
Dan Roney
sumedhb1995