The general idea here is that the "header" describes mechanical aspects
of installing / using the library. Where the "footer" enumerates
relevant Fluid Framework policies. The API docs belong in the former
category.
Bumps the client dependencies on build-tools to 0.41.0.
## Automated changes
- The type test generator was updated in this build-tools release, so
the output of all type tests was regenerated.
## Manual changes
- The type test generator uses new names in some cases, which means
existing test disables in package.json had to be renamed. This extra
step could have been avoided if I'd done the bump after the next
release, when the type tests are all reset and the disables are all
reset. But this release contains useful changes and is worth getting
into the release branch as well.
- The azure-client disables needed an additional entry,
"RemovedClassStatics_AzureFunctionTokenProvider" which is expected.
The existence of a singular "library package README" transformation
encourages developers to not include other necessary details in package
READMEs. It was also previously unused in a lot of places because it was
difficult to interleve the common details with custom ones.
This PR removes that template and introduces 2 new ones: a "header"
template and a "footer" template, with recommended guidance for where
each should be used.
Also updates existing consumers of the removed template to migrate to
the new ones.
Changes:
1. Remove production dependency in
@fluid-example/bubblebench-shared-tree
2. Update versions to ~1.8.3 (and set config to want ~)
3. Handle deprecations
a. Replace "javascript.formatter.trailingComma" with "...trailingCommas"
b. Replace cli argument `--apply` with `--write`
4. Apply formatting updates
5. Add Biome to npm-package-json-script-dep
6. Remove unused `--formatter-enabled=true` from commands
7. Add missing biome devDeps in build-tools
Under 1.7.3 VS Code extensions users could experience server connection failures and need 1.8 version to get support from Biome. See [biomejs/biome-vscode#261](https://github.com/biomejs/biome-vscode/issues/261)
Update legacy report generation to emit public report ahead of updating
some `@legacy+@alpha` APIs to be `@legacy+@public`.
New `*.legacy.public.api.md` reports are identical to existing
`*.public.api.md` except for these four where there are spurious exports
listed for re-exports of external packages:
- azure/packages/azure-service-utils
- packages/common/container-definitions
- packages/dds/sequence
- packages/service-clients
## Description
```
pnpm exec flub typetests -g client --private --disable
pnpm exec flub typetests -g client --reset --previous --normalize
pnpm i
pnpm run build:fast
```
This disabled type tests in two private packages which did not have type
tests, but also didn't mark themselves as having disabled type tests:
- @fluid-tools/markdown-magic
- @fluid-private/changelog-generator-wrapper
API breaks in these packages were restored (If the type test baselines
were bumped wright after the branch spilt this list should be empty, but
2.0 had a longer fork to release delay than normal for stabilization, as
well as a delay before updating these baselines):
- @fluidframework/odsp-driver-definitions
- @fluidframework/container-definitions
- @fluidframework/file-driver
- @fluidframework/azure-client
in all packages with legacy exports
Split api-extractor report generation to `build:api-report` task (when
it is not done as part of `build:docs`).
+ add `api-extractor-model.esm.json` as common config for all
`build:docs` that are just concerned with *.api.json generation.
+ rename shared report configs to say `api-extractor-report` to indicate
that is what they cover.
Changes for each impacted package:
1. new `api-extractor/api-extractor.current.json` using `public.d.ts`
entrypoint for `*.(public|beta).api.md` generation (there are no `@beta`
APIs currently)
2. `api-extractor.json` just used for doc model `*.api.json`generation
3. `api-extractor/api-extractor.legacy.json` edited for common
`api-extractor-report.esm.legacy.json` rename
4. package.json - script split up
\* client-utils is special per browser/node entrypoints
Fixes build defect where packages with legacy exports would double
generate `*.api.json` doc model and `tsdoc-metadata.json` from two
different commands. (Generation from the legacy report step was
extraneous and luckily always the same for packages where that
happened.)
`*.(public|beta).api.md` changes show API removal of types that are not
real exports, but collateral from api-extactor previously keying off of
internal entrypoint (index.d.ts).
Updated the following:
client (release group)
Dependencies on build-tools updated:
@fluid-tools/build-cli: 0.40.0
@fluidframework/build-tools: 0.40.0
@fluidframework/bundle-size-tools: 0.40.0
@fluid-tools/version-tools: 0.40.0
## Automated changes
This update caused two major changes:
- type tests are now more compact and several bugs have been addressed.
- Some api reports have comment-only changes.
## Manual changes
I also noticed that odsp-doclib-utils had a lint config that did not
extend from "prettier," so some lint rules that shouldn't be running
were getting triggered on the type tests. Extending the prettier config
resolved the problem.
Finally, I added an exclusion of the npm-metadata-and-sorting policy for
the root package.json because of
[AB#8640](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/8640),
which I'll resolve later.
Our github wiki isn't really tailored for public consumers; that's what
our website is for.
This PR updates our README "Help" template (and all consuming READMEs)
to point users exclusively to our website for learning.
The repository.directory field is not correct for some packages. I
updated the broken ones using the policy in #21605. That policy will
protect against future issues once it's merged and brought into the
client release group.
In client group for packages with `/legacy` exports (not `examples`,
`experimental`, and `packages/tools/devtools`):
- search: `^(?<!@legacy\n)(\s+\* )@alpha`
- replace: `$1@legacy\n$1@alpha`
- search: `/** @alpha */`
- replace: `/**\n * @legacy\n * @alpha\n */`
+ remove all uses of `--outFileAlpha legacy` which allows `legacy.d.ts` to be generated from `@legacy` tags.
`@alpha` is now reclaimed for tradition use.
[AB#8144](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/8144)
legacy report is still generated to ".alpha.api.md" to track transition.
Ideally no reports would change here, but api-extractor both cleans up
some cruft and adds more when using the rollup. The actual APIs listed
are unchanged.
Comments added about missing `@packageDocumentation` to be addressed by [AB#8516](https://dev.azure.com/fluidframework/internal/_workitems/edit/8516): `flub generate entrypoints` should preserve `@packageDocumentation`
Imports are currently untrimmed in API reports, meaning that _all_
imports that affect the API appear in _all_ reports, regardless of
release level (e.g. imports used only by `@alpha` items appear in public
reports). This creates a lot of noise for reviewers, and the information
is misleading anyways.
Fixing API-Extractor to correctly trim imports is being tracked by
[AB#8467](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/8467).
Command used to reset the tests and use RC5:
```shell
flub typetests -g client --reset --normalize --exact 2.0.0-rc.5.0.0
```
I also manually removed the `--publicFallback` flag from the `flub
generate typetests` command where it was used. It's no longer needed
because the previous versions now expose the ./internal entrypoint.
### Exceptions
I'll follow up on these later this week after the main branch is
unlocked.
**driver-definitions**: Type tests were mostly busted for this project,
I think due to massive changes in the exported API surface in #21200. I
switched it to test only the _public_ API instead of internal, which
isn't ideal but better than disabling the tests completely. It's not
clear to me if this represents a real customer-impacting break or not.
**file-driver**: This type test required _forward-compatibility_
overrides: VariableDeclaration_FluidFetchReaderFileSnapshotWriter
I think that's OK, but if not we can follow up with a separate change.
Bumped client from 2.0.0-rc.5.0.0 to 2.1.0, the next version we intend
to release from main.
Command used:
```shell
flub bump client --exact 2.1.0
```
Includes the changes in #21346 which were needed to get this PR to pass
CI.
---------
Co-authored-by: Scott Norton <scottnorton@microsoft.com>
Updated the following:
client (release group)
Dependencies on server updated:
@fluidframework/gitresources: ^5.0.0
@fluidframework/server-kafka-orderer: ^5.0.0
@fluidframework/server-lambdas: ^5.0.0
@fluidframework/server-lambdas-driver: ^5.0.0
@fluidframework/server-local-server: ^5.0.0
@fluidframework/server-memory-orderer: ^5.0.0
@fluidframework/protocol-base: ^5.0.0
@fluidframework/server-routerlicious: ^5.0.0
@fluidframework/server-routerlicious-base: ^5.0.0
@fluidframework/server-services: ^5.0.0
@fluidframework/server-services-client: ^5.0.0
@fluidframework/server-services-core: ^5.0.0
@fluidframework/server-services-ordering-kafkanode: ^5.0.0
@fluidframework/server-services-ordering-rdkafka: ^5.0.0
@fluidframework/server-services-ordering-zookeeper: ^5.0.0
@fluidframework/server-services-shared: ^5.0.0
@fluidframework/server-services-telemetry: ^5.0.0
@fluidframework/server-services-utils: ^5.0.0
@fluidframework/server-test-utils: ^5.0.0
tinylicious: ^5.0.0
Command used:
```
flub bump deps server -g client --updateChecker homegrown
```
I also updated the lockfile resolution of the debug package to be 4.3.5,
the latest patch. Command used:
```shell
flub modify lockfile -g client --dependencyName=debug --version=^4.3.5
```
This was needed because the new server version brought in the new debug
version, so we had two versions when bundled, which our bundle-size
tests caught. By resolving uniformly to the latest, we unified the
version across client and server.
- packages without /legacy exports use
api-extractor-base.*.no-legacy.json
- packages with /legacy exports use api-extractor-base.esm.cuurent.json
api-extractor-base.*.primary.json are replaced.
- cjs version is exactly .csj.no-legacy.json.
- esm version is now .esm.json but is used via .esm.no-legacy.json or
.esm.current.json.
The few direct references to api-extractor-base.json are replaced with
one of the new three files. api-extractor-base.json no longer specifies
reportVariants as api-extractor config inheritance does not handle array
overrides well.
Future: .esm.legacy.json will be added for packages with /legacy exports
and handle those APIs specifically.
## Summary
The client release group is updated to use biome for formatting instead
of prettier.
## Changes
1. The `format` script in each package now calls biome instead of
prettier.
2. The root `format` task runs a single biome command from the root
instead of running format in every package.
3. The vscode root workspace settings have been updated to set the biome
extension as the default formatter.
4. The root biome config is now in JSONC instead of JSON.
5. Paths outside the client and build-tools release groups are ignored
in the biome config because they're not using biome (yet).
## Known issues
- Despite best efforts, formatting back and forth between biome and
prettier is not 100% fidelity. Some changes that biome makes prettier
does not revert, though it also doesn't start failing or anything. You
can see examples by running `pnpm format && pnpm format:prettier` from
the root and looking and the remaining changes.
- Reformatting does sometimes cause lint disable statements to get
misplaced and they have to be manually fixed up.
- Created common `tsdoc-base.json` with `@legacy` and `@system` tags.
- Used `flub exec -g client` to place a `tsdoc.json` file wherever
`api-extractor.json` existed.
- Added `tsdoc.json` to `devtools-view` and `example-utils`.
1. apply npm-package-exports-apis-linted policy with --fix
2. suppress checks where there are active violations
3. task cleanup before check:release-tags removal
4. remove check:release-tags from packages with
check:exports:bundle-release-tags
5. remove check:release-tags to with check:exports where no
check:exports:bundle-release-tags (private packages where policy does
not apply)
[AB#8142](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/8142)
Updated the following:
- client (release group)
- client-release-group-root
Dependencies on build-tools updated:
- `@fluid-tools/build-cli`: 0.39.0
- `@fluidframework/build-tools`: 0.39.0
- `@fluidframework/bundle-size-tools`: 0.39.0
- `@fluid-tools/version-tools`: 0.39.0
- `@oclif/core` allowed to update - required by `@fluid` updates
Ran build to generate new typetest sources for changes in
https://github.com/microsoft/FluidFramework/pull/19224.
- `@sealed` tag to disables "forwards" compatibility testing making
extending sealed types not a breaking change. More docs are in progress
about this in https://github.com/microsoft/FluidFramework/pull/14421
- Make type tests import type preprocessors instead of inlining their
source. This (among other things) allows navigating to their
implementations and viewing the IntelliSense documenting the different
validators mentioned above.
- Add support for "MinimalType" (`@type-test-minimal`) and "FullType"
(``@type-test-full``) tags to opt into stricter validation or out of
validation via type preprocessors. These are mainly intended as
workarounds for type-testing limitations, and an incremental step toward
enabling more strict testing by default.
---------
Co-authored-by: Tyler Butler <tyler@tylerbutler.com>
## Summary
Adds several scripts that can be run to convert projects in the client
release group to use the biome formatter. The process can be effectively
reversed by running another script, so projects can switch between
prettier and biome using the scripts and the build will continue to
work.
After enabling biome formatting, you can manually format using biome
with the `format:biome`script.
Once projects are completely on biome and we no longer need to port
changes between prettier branches and biome branches, then we can remove
prettier completely using the remove-prettier script. We should only do
that once the last release branch using prettier is no longer in
service.
## Scripts
### add-biome.sh
This script adds biome formatting scripts to a project. It also adds a
local biome config file to the project if needed.
The `format:prettier` and `check:prettier` tasks are left intact, and
the `format` task still calls prettier. This
enables one to manually format using biome while leaving the overall
build using prettier.
After running this script, you can clean up the package.json files by
running `pnpm policy-check:fix`.
**This PR includes the changes made by running this script across the
client release group.**
### enable-biome.sh
This script enables biome formatting in a project. It updates the
`format` and `check:format` scripts to call biome. It
should only be run on projects that have already had biome added to it.
### enable-prettier.sh
This script enables prettier formatting in a project. It updates the
`format` and `check:format` scripts to call
prettier. It's the opposite of the enable-biome.sh script.
### remove-prettier.sh
Once a project is completely switched to biome and no longer needs
prettier, this script will remove the prettier
dependency and any related scripts and config files.
Bumping server dependencies to prerelease version in the client release
group to access new [targeted signal
capabilities](https://github.com/microsoft/FluidFramework/pull/19519) on
the client side.
Will need confirmation from FF release engineer(s) since they will be
the person who will have to do the real server release.
I used the following command to complete the bump from the repo root:
`flub bump deps server -g client -t greatest --prerelease`
I then did `pnpm install` to update the pnpm-lock file.
Each package now generates API reports for each release level alpha,
beta, and public. These reports correspond with the trimmed roll-ups
API-Extractor generates for each release level. This offers convenient
insight into which APIs of a given package are available in which
entrypoint(s). It also offers a mechanism for tracking API items as they
are promoted to higher levels of support guarantees.
For now, we are not generating reports for internal-level exports. This
is intentional but does not have to be a permanent change. If we decide
in the future that it would be valuable to track our internal API
surfaces, we can add that level to the set of reports we generate.
These changes also exclude the packages under `build-tools`, as those
packages don't leverage type-trimming, nor do they manage multiple
entrypoints.
[AB#7523](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/7523)
### Some notes for reviewers
1. Reports for empty package APIs are still generated, and simply don't
contain export details. We may wish to file a feature request to make
this a bit cleaner. Probably append a notice that there are no exports
at the given release level.
2. "Trimmed" reports will contain "untrimmed" imports. This matches the
behavior of the corresponding typings rollups, but it's not particularly
interesting from a report perspective, and could create noise in
automated review enforcement. We should probably file a feature request
around this too, possibly just a way to opt out of including imports in
the report file (I don't think we generally want them there anyways).
Updated the following:
client (release group)
Dependencies on @fluidframework/eslint-config-fluid updated:
@fluidframework/eslint-config-fluid: 5.3.0
There were some code changes needed to adhere to the lint config. They
were partially automated then I manually fixed up others.
This adds the types defined in 'protocol-definitions' to
'driver-definitions' and updates client dependencies/imports to use the
'driver-definitions' types.
This is a large review. If using GitHub, I recommend:
a. Use FireFox
b. Use `document.querySelectorAll('.load-diff-button').forEach((button)
=> button.click());` to expand diffs
The approximate process used was:
1. Copy types to src/protocol/*.ts
2. S&R to update dependencies in package.json
3. S&R to replace 'from "...protocol-definitions"' to 'from
"...driver-definitions"'
4. Use tools to clean up:
a. pnpm i
b. 'flub modify fluid-imports --onlyInternal
--packageRegex=driver-definitions'
c. npm run format
d. npm run policy-check:fix
Other notable changes:
* Required minor adjustments to layerInfo.json
* Semi-automatically expanded 'import * as api from ...' to regular
imports for 'flub modify'.
* Needed to export 'ISequencedDocumentMessage' from 'fluid-framework'
(not a new dependency, we just need to be explicit.)
## Description
Typescript 5.3 brings useful features like support for
[Symbol.hasInstance
narrowing](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-3.html#instanceof-narrowing-through-symbolhasinstance),
type checking optimizations and much more. Since ClientRequirements.md
lists our requirement at TypeScript 5.4, this should be ok (from the
perspective of aligning with that requirement)
See
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html
and
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-3.html
for more details.
Based on a two test runs, this change makes `pnpm run build:compile`
about 7% faster. (105.438 and 107.011 seconds instead of 113.816 and
114.096 without the change)
## Breaking Changes
This is not expected to break anything, however its possible that the
compile TypeScript is slightly different, which could cause issues in
some edge cases.
This will enable code to start relying on newer features, which when
used in public APIs could in turn cause breakages for users of older
versions of TypeScript.
There are a couple cases where type-tests were impacted. These seemed to
be a fix of typescript capturing more accurate types, especially around
index signatures, and cases where the TypeScript compiler wouldn't
provide any useful information about what changed with the only
difference being inside the `...` non-printed parts of the types. As the
changes seem relatively minor they seem unlikely to cause any real
issues (didn't break lots of examples/tests) and since we only support
customers using TypeScript 5.4 and plan to move to 5.4 ourselves at some
point, if this causes a breaking change in some edge case, that probably
a good thing to get out of the way now while we are still in the RC
phase.
## Description
https://github.com/microsoft/FluidFramework/pull/21070 made some
improvements to type tests which were needed to regenerate the type
tests for client. This change integrates that, as well as regenerates
the type tests with the new generator.
Updates dependency from `7.42.3` to `7.43.1`.
Also makes a small type correction in tree to resolve issue surfaced by
API-Extractor's bundled `typescript@5.4.2`.
Updated the following:
client (release group)
Dependencies on build-tools updated:
@fluid-tools/build-cli: 0.38.0
@fluidframework/build-tools: 0.38.0
@fluidframework/bundle-size-tools: 0.38.0
@fluid-tools/version-tools: 0.38.0
Manual fixes:
- client-utils does not have an internal entrypoint, so I updated its
typetests:gen task to use the public entrypoints explicitly: `flub
generate typetests --dir . -v --level public`
This PR introduces the following enhancements:
1. Renamed `AzureMember.userName` to `AzureMember.name` to establish
uniform naming across odsp-client and azure-client modules.
2. Updated `IMember.userId` to `IMember.id` to align with the properties
received from AFR.
3. Replaced all occurrences of `userId` with `id` and `userName` with
`name` for consistency.
Updates the type tests previous versions to RC3. There were several
packages that still have broken tests, but rather than try to review
those here, I recommend we merge this and I will follow up with a
separate PR that resets all broken tests and review that PR with package
owners to verify the breaks are legitimate.
This PR does bump the previous versions, so it is beneficial to merge
as-is rather than waiting for more changes from specific projects.
## Description
The telemetry logger usage should follow these two principals:
- ITelemetryLoggerExt should be only used by @internal
- ITelemetryBaseLogger can be used by @public, @alpha, @beta
Find the spitting point that public APIs start to use Ext instead of
Base. Change it and fix it.
This is the list of types that we have identified that we need to "hide"
(make @alpha or @internal instead of @public). It may not be exhaustive,
so if we find more types that need changes, we should address them too.
- **TelemetryEventCategory**
- **TelemetryEventPropertyTypeExt**
- **ITelemetryPropertiesExt**
- **ITelemetryGenericEventExt**
- **ITelemetryErrorEventExt**
- **ITelemetryPerformanceEventExt**
- **ITelemetryLoggerExt**
- ~~ITelemetryContext~~
---------
Co-authored-by: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com>
Co-authored-by: Alex Villarreal <716334+alexvy86@users.noreply.github.com>
Joshua Smithrud
Tyler Butler
Jason Hartman
Craig Macomber (Microsoft)
Matt Rakow
Rishhi Balakrishnan
WillieHabi
Daniel Lehenbauer
Zach Newton
Jatin Garg
Sonali Deshpande
Tong Chen