Components: Warn private API in auto-generated readmes #68317
Conversation
mirka
added
[Type] Developer Documentation
|
Flaky tests detected in 1111d07. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/12503252241
|
| tags.includes( 'status-private' ) && [ | ||
| { | ||
| p: '🔒 This component is locked as a [private API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-private-apis/). We do not yet recommend using this outside of the Gutenberg project.', | ||
| }, | ||
| ], |
There was a problem hiding this comment.
Using normal Markdown instead of a div callout, because the intended audience is not on Block Editor Handbook.
|
|
||
|
|
There was a problem hiding this comment.
Redundant newlines will be fixed in #68301.
| const meta: Meta< typeof Badge > = { | ||
| component: Badge, | ||
| title: 'Components/Containers/Badge', | ||
| id: 'components-badge', | ||
| tags: [ 'status-private' ], | ||
| } satisfies Meta< typeof Badge >; | ||
| }; |
There was a problem hiding this comment.
Normalizing this declaration to our standard format (not TS satisfies) for easier AST parsing.
There was a problem hiding this comment.
Thanks for this 👍 The satisfies syntax seemed to cause some issues when parsing files for component usage as well.
| */ | ||
| export async function getTagsFromStorybook( filePath ) { | ||
| const fileContent = await fs.readFile( filePath, 'utf8' ); | ||
| const parsedFile = babel.parse( fileContent, { |
There was a problem hiding this comment.
These bin scripts aren't set up to process TS files yet (e.g. index.story.tsx files), so we can't read data from import()ed meta objects. At the moment I think it's simpler to do a quick AST parse than set up TS transpilation just for this, but we can maybe revisit when there are more use cases.
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
| const meta: Meta< typeof Badge > = { | ||
| component: Badge, | ||
| title: 'Components/Containers/Badge', | ||
| id: 'components-badge', | ||
| tags: [ 'status-private' ], | ||
| } satisfies Meta< typeof Badge >; | ||
| }; |
There was a problem hiding this comment.
Thanks for this 👍 The satisfies syntax seemed to cause some issues when parsing files for component usage as well.
| const mainDocsJson = [ | ||
| { h1: typeDocs.displayName }, | ||
| '<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->', | ||
| tags.includes( 'status-private' ) && [ | ||
| { | ||
| p: '🔒 This component is locked as a [private API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-private-apis/). We do not yet recommend using this outside of the Gutenberg project.', |
There was a problem hiding this comment.
In an ideal world, and accoding to @jsnajdr's latest suggestions, a 3rd party developer simply should be unable to use private APIs outside of Gutenberg.
What?
Detects private API status from the component's Storybook file to add a warning in the auto-generated README.
Why?
Although the READMEs for private components are not published to the Block Editor Handbook, people can see the READMEs directly in the repo. And currently they don't show which components are still private.
Testing Instructions
✅
npm run docs:componentsto regenerate