improvement(build-common): Allow APIs to {@link} to APIs of lower release levels.
#23533
Conversation
github-actions
bot
added
area: build
There was a problem hiding this comment.
Copilot reviewed 2 out of 5 changed files in this pull request and generated no comments.
Files not reviewed (3)
- common/build/build-common/api-extractor-lint.entrypoint.json: Language not supported
- common/build/build-common/api-extractor-report.esm.current.json: Language not supported
- common/build/build-common/api-extractor-report.esm.legacy.json: Language not supported
common/build/build-common/api-extractor-report.esm.current.json
Outdated
Show resolved
Hide resolved
| @@ -13,5 +13,17 @@ | |||
| // second time via "legacy" report. | |||
| "tsdocMetadata": { | |||
| "enabled": false | |||
| }, | |||
| "messages": { | |||
| "extractorMessageReporting": { | |||
There was a problem hiding this comment.
would be practical to have this config extend api-extractor-report.esm.current.json so that it didn't need to duplicate things we want for report generation, and only do legacy specific stuff?
There was a problem hiding this comment.
Hopefully that or something similar. Was hoping to get @jason-ha's eyes on this to advise.
There was a problem hiding this comment.
api-extractor has trouble with merging array properties. And unfortunately, doesn't allow multiple inheritance. Ideally there would be a base model config and several other shareable config pieces.
The best we can do is reduce to two configs with manipulation of this message.
Option A (one more duplication of "tsdocMetadata" overall; my preference):
- Place this in
-base(and turn-off model by default). - Add
-base.model(or-base_with_model) that turns on model and that message. - Change
-base.cjs.no-legacyand-model.esmto extend-base.model. - Update
-base.esm.no-legacyto:- Extend
-base.model. - Specify "mainEntryPointFilePath": "/lib/index.d.ts" (can be deleted from
-base.esm). - Specify "tsdocMetadata" as found in
-base.esm.
- Extend
- Optional (recommended):
- Delete
-base.esm.- Add "tsdocMetadata" as was found in
-base.esminto-report.esm.current.
- Add "tsdocMetadata" as was found in
- For good measure add "apiReport.enabled": true to both
-report.esm.currentand-report.esm.legacy. - Remove "explicit docModel" disable from
-lint,-lint.entrypoint,-report.esm.current, and-report.esm.legacy.
- Delete
Option B (three copies of docModel disable with message change):
- Add
-report.base.ems(alternatively-base.esm.no-model) that inherits-base.esm- Disable "docModel" and turn off message
-report.esm.currentand-report.esm.legacywould inherit new-report.base.emsand stop disabling "docModel".- optional (recommended): move
-base.esm'smainEntryPointFilePathsetting to.esm.no-legacy.
There was a problem hiding this comment.
On the note of array merge: microsoft/rushstack#5071
There was a problem hiding this comment.
Went with A above. Named the new config -mode-base, but I can change that if you feel strongly.
There was a problem hiding this comment.
Longer term: this hierarchy of configs is very confusing. I wonder if we would be better suited by adding a simple generator that spits out complete configs based on input parameters.
⯅ @fluid-example/bundle-size-tests: +245 Bytes
Baseline commit: cf15304 |
…lower-release-levels
…se-levels' of https://github.com/microsoft/FluidFramework into build-common/api-extractor/allow-linking-to-lower-release-levels
Since we generate API reports for different release levels, it is possible (and valid) for
@linktags to reference an API item that won't be visible at that level. Currently, our configurations forbid such links as a side-effect of running link validation during report generation (where APIs will be omitted from report consideration based on their release tags.However, it is often useful for APIs to link to more experimental APIs for discoverability.
To make this possible, link validation is now disabled in report generation configurations. It is maintained in model generation configs, which is where we really need it.
Also adds a couple of such links in the
treepackage as a test (and because we wanted them there).