Reshaping Contributing docs #67785
Reshaping Contributing docs #67785
Conversation
Adding new docs on how to contribute to WPDS, including specific guidance for documentation and components
|
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. |
juanbuis
added
the
Design System
|
Warning: Type of PR label mismatch To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.
Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task. |
|
👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @juanbuis! In case you missed it, we'd love to have you join us in our Slack community. If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information. |
github-actions
bot
added
the
First-time Contributor
juanbuis
added
Needs Testing
|
This is my first PR at WordPress, so apologies if I'm doing anything wrong — I'm open to any feedback! :) |
|
Hi @juanbuis 👋 I'm answering the "Needs Copy Review" ping. Can you point me to the copy you'd like reviewed? |
Thank you! Would love a read-through of all new pages that have been added with this PR: storybook/stories/contributing/contributing-components.txt |
|
|
||
| Because components are an important part of our design system and it’s WordPress policy to make them backwards compatible, contributions to them are seen as major changes. | ||
|
|
||
| While changing a typo in our documentation can be shipped quite quickly, work on components requires more time and attention from our design community. |
There was a problem hiding this comment.
Instruction opportunity: If you have a small fix like a typo do [this], if you have an enhancement do [that]. (using enhancement as a term because is the GitHub label we use for improvements). I'd also be more explicit about what goes into getting a component contribution in, like for example 'component work requires at least one formal review from a designer'.
| - How much effort will be required to create and maintain it? | ||
| - Is there a clear purpose for it? |
There was a problem hiding this comment.
These questions are great. I think they might have even more impact if instead of a deterrent, they could be part of a quality assurance checklist that or something of sorts?
| - Does it overlap functionally or visually with any existing components? Can we use existing components to implement an alternative solution? | ||
| - How much effort will be required to create and maintain it? | ||
| - Is there a clear purpose for it? | ||
| - Can we introduce this change without causing breaking changes? Will we be able to keep this change and iterate on it in the future without causing future breaking changes? |
There was a problem hiding this comment.
Is this a breaking change? And maybe link to what makes a breaking change?
There was a problem hiding this comment.
I can't find WordPress guidance on what makes a breaking change — do you think I could link out to general guidance?
Alternatively, we could rewrite to something like:
“Can we make this change without causing a breaking change (something that forces users to update their setup or workflows to keep things working) and will it allow future updates without similar issues?”
Co-authored-by: Au <[email protected]>
Co-authored-by: Au <[email protected]>
Co-authored-by: Au <[email protected]>
|
Just to recap my conversation with @juanbuis—my understanding is that this text has already been reviewed by Michael Pick. |
Adding new docs on how to contribute to WPDS, including an overview, how to get started with contributing, and specific guidance for documentation and components.
Related issue: #66016
What?
Why?
Make it easier for anyone to get started contributing to the design system.
How?
Rewritten pages with clearer structure, an overview page, a new page that explains contributing to documentation, various step-by-step guides, a "how to get started" guide, plus a new "Contributing" section that holds it all.
Testing Instructions
Please check for inaccuracies, missing content, language.
Also I'd love for someone to check if i edited storybook/preview.js correctly