Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Don't strip out @alpha items from generated reports #4329

Merged
merged 3 commits into from
Sep 29, 2023
Merged

Don't strip out @alpha items from generated reports #4329

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aa81d5d
Don't strip out `@alpha` items from report
Josmithr Sep 14, 2023
71d2f0c
feat(api-documenter): Support annotation of alpha APIs
Josmithr Sep 19, 2023
a2f5b22
docs: Add changesets
Josmithr Sep 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 21 additions & 4 deletions apps/api-documenter/src/documenters/MarkdownDocumenter.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,9 @@ export class MarkdownDocumenter {
}

if (ApiReleaseTagMixin.isBaseClassOf(apiItem)) {
if (apiItem.releaseTag === ReleaseTag.Beta) {
if (apiItem.releaseTag === ReleaseTag.Alpha) {
this._writeAlphaWarning(output);
} else if (apiItem.releaseTag === ReleaseTag.Beta) {
this._writeBetaWarning(output);
}
}
Expand Down Expand Up @@ -1000,10 +1002,13 @@ export class MarkdownDocumenter {
const section: DocSection = new DocSection({ configuration });

if (ApiReleaseTagMixin.isBaseClassOf(apiItem)) {
if (apiItem.releaseTag === ReleaseTag.Beta) {
if (apiItem.releaseTag === ReleaseTag.Alpha || apiItem.releaseTag === ReleaseTag.Beta) {
section.appendNodesInParagraph([
new DocEmphasisSpan({ configuration, bold: true, italic: true }, [
new DocPlainText({ configuration, text: '(BETA)' })
new DocPlainText({
configuration,
text: `(${apiItem.releaseTag === ReleaseTag.Alpha ? 'ALPHA' : 'BETA'})`
})
]),
new DocPlainText({ configuration, text: ' ' })
]);
Expand Down Expand Up @@ -1152,10 +1157,22 @@ export class MarkdownDocumenter {
}
}

private _writeAlphaWarning(output: DocSection): void {
const configuration: TSDocConfiguration = this._tsdocConfiguration;
const betaWarning: string =
'This API is provided as an alpha preview for developers and may change' +
dmichon-msft marked this conversation as resolved.
Show resolved Hide resolved
' based on feedback that we receive. Do not use this API in a production environment.';
output.appendNode(
new DocNoteBox({ configuration }, [
new DocParagraph({ configuration }, [new DocPlainText({ configuration, text: betaWarning })])
])
);
}

private _writeBetaWarning(output: DocSection): void {
const configuration: TSDocConfiguration = this._tsdocConfiguration;
const betaWarning: string =
'This API is provided as a preview for developers and may change' +
'This API is provided as a beta preview for developers and may change' +
' based on feedback that we receive. Do not use this API in a production environment.';
output.appendNode(
new DocNoteBox({ configuration }, [
Expand Down
2 changes: 1 addition & 1 deletion apps/api-documenter/src/documenters/YamlDocumenter.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -425,7 +425,7 @@ export class YamlDocumenter {
}

if (ApiReleaseTagMixin.isBaseClassOf(apiItem)) {
if (apiItem.releaseTag === ReleaseTag.Beta) {
if (apiItem.releaseTag === ReleaseTag.Alpha || apiItem.releaseTag === ReleaseTag.Beta) {
yamlItem.isPreview = true;
}
}
Expand Down
4 changes: 2 additions & 2 deletions apps/api-extractor/src/generators/ApiModelGenerator.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,8 +176,8 @@ export class ApiModelGenerator {

const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
if (releaseTag === ReleaseTag.Internal || releaseTag === ReleaseTag.Alpha) {
return; // trim out items marked as "@internal" or "@alpha"
if (releaseTag === ReleaseTag.Internal) {
return; // trim out items marked as "@internal"
}

switch (astDeclaration.declaration.kind) {
Expand Down
10 changes: 10 additions & 0 deletions common/changes/@microsoft/api-documenter/patch-1_2023-09-20-22-22.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"changes": [
Josmithr marked this conversation as resolved.
Show resolved Hide resolved
{
"packageName": "@microsoft/api-documenter",
"comment": "Add notes for @alpha items when encountered. Mimics the existing behavior for @beta items.",
"type": "patch"
}
],
"packageName": "@microsoft/api-documenter"
}
10 changes: 10 additions & 0 deletions common/changes/@microsoft/api-extractor/patch-1_2023-09-20-22-22.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"changes": [
{
"packageName": "@microsoft/api-extractor",
"comment": "Don't strip out @alpha items when generating API reports.",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dmichon-msft for future reference, this should have been a MINOR version bump. It is a significant behavioral change that may cause previously undisclosed content to appear on a public website.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gah, I've gotten so used to the Rush projects where the version bump isn't part of the PR that I forgot to check that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the process for correcting this? I'm happy to put up a PR fixing this if I can get guidance.

"type": "patch"
}
],
"packageName": "@microsoft/api-extractor"
}