Adding example readme template to contributing guidelines. #34847
+37
−0
Conversation
added 7 commits
Sep 15, 2021
ciampo
reviewed
Sep 16, 2021
Thank you @ryanwelcher for adding this section to the CONTRIBUTING guidelines!
| ``` | ||
| # ComponentName | ||
| If component is experimental, add the following section: |
Let's make this line a comment
Suggested change
| If component is experimental, add the following section: | |
| <!-- If component is experimental, add the following section: --> |
| ##### Readme example | ||
|
|
||
| ``` | ||
| # ComponentName |
Debatable: should the ComponentName be formatted in monospaced font?
Suggested change
| # ComponentName | |
| # `ComponentName` |
| @@ -292,6 +292,43 @@ All components, in addition to being typed, should be using JSDoc when necessary | |||
|
|
|||
| Each component that is exported from the `@wordpress/components` package should include a `README.md` file, explaining how to use the component, showing examples, and documenting all the props. | |||
|
|
|||
| ##### Readme example | |||
We'll need to re-assess the heading's level since #34877 got merged
| This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. | ||
| </div> | ||
| If component is deprecated, add the following section: |
As above
Suggested change
| If component is deprecated, add the following section: | |
| <!-- If component is deprecated, add the following section: --> |
| ### propName | ||
| Prop description. With a new line before and after the description and before and after type/required blocks. | ||
| - Type: Typescript style type i.e `string`, `number`, `( nextValue: string ) => void` | ||
| - Required: Either`yes` or `no` |
I wonder if we should adopt a slightly different format
Suggested change
| ### propName | |
| Prop description. With a new line before and after the description and before and after type/required blocks. | |
| - Type: Typescript style type i.e `string`, `number`, `( nextValue: string ) => void` | |
| - Required: Either`yes` or `no` | |
| ### `propName`: Typescript style type i.e `string`, `number`, `( nextValue: string ) => void` | |
| Prop description. With a new line before and after the description and before and after type/required blocks. | |
| - Required: Either `yes` or `no` |
I've adopted this format in a few components recently (e.g. ItemGroup) and I quite liked it because the type can be spotted more easily.
| @@ -292,6 +292,43 @@ All components, in addition to being typed, should be using JSDoc when necessary | |||
|
|
|||
| Each component that is exported from the `@wordpress/components` package should include a `README.md` file, explaining how to use the component, showing examples, and documenting all the props. | |||
|
|
|||
| ##### Readme example | |||
|
|
|||
| ``` | |||
Suggested change
| ``` | |
| ```md |
| ## Usage | ||
| Code example using correct markdown syntax and formatted using project's formatting rules. |
Suggested change
| Code example using correct markdown syntax and formatted using project's formatting rules. | |
| Code example using correct markdown syntax and formatted using project's formatting rules. See [ItemGroup](/packages/components/src/item-group/item-group/README.md#usage) for a real-world example. | |
| ```jsx | |
| import { ExampleComponent } from '@wordpress/components'; | |
| function Example() { | |
| return ( | |
| <ExampleComponent> | |
| <p>Code is poetry</p> | |
| </ExampleComponent> | |
| ); | |
| } |
| ### Inherited props | ||
| Add this section when there are props that are drilled down into an internal component. See [ClipboardButton](/packages/components/src/clipboard-button/README.md) for an example. |
We should add an optional section about context
Suggested change
| Add this section when there are props that are drilled down into an internal component. See [ClipboardButton](/packages/components/src/clipboard-button/README.md) for an example. | |
| Add this section when there are props that are drilled down into an internal component. See [ClipboardButton](/packages/components/src/clipboard-button/README.md) for an example. | |
| <!-- Only add the next section if the component relies on the [Context System](#context-system) --> | |
| ## Context | |
| See examples for this section for the [ItemGroup](/packages/components/src/item-group/item-group/README.md#context) and [`Card`](/packages/components/src/card/card/README.md#context) components. |
ciampo
moved this from In progress (owned) ⏳
to In progress ⏳ (un-owned)
in WordPress Components
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Description
Adding an example Readme to Contributing.md to work as a style guide to remove guesswork around formatting. Closes #34694
Types of changes
Docs only
Checklist:
*.native.jsfiles for terms that need renaming or removal).The text was updated successfully, but these errors were encountered: