From 6ea51d6ac6f2585dbd4086dcd1144655f84cb5f6 Mon Sep 17 00:00:00 2001 From: Dave Whitley Date: Wed, 31 Jul 2019 15:00:23 -0500 Subject: [PATCH 1/4] Initial commit Add component contribution guidelines --- packages/components/src/CONTRIBUTING.md | 80 +++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 packages/components/src/CONTRIBUTING.md diff --git a/packages/components/src/CONTRIBUTING.md b/packages/components/src/CONTRIBUTING.md new file mode 100644 index 00000000000000..b8480994517a35 --- /dev/null +++ b/packages/components/src/CONTRIBUTING.md @@ -0,0 +1,80 @@ +# Contributing components + +These guidelines document how to contribute to components in the [`@wordpress/components`](https://www.npmjs.com/package/@wordpress/components) npm package, or “WordPress Components”. This can be addition, modification, or deprecation. + +## Does it belong in the component library? + +A component library should include what’s shared across many products and omit what’s not. Questions to help determine if a component should be added: + +- Is it relevant to other products/plugins? +- Is there overlap with any existing components? +- How much will it cost to make and maintain? +- Can you articulate how the component should be used? + +Here’s a flowchart that can help determine if a new component is necessary: + +[![New component flowchart](https://wordpress.org/gutenberg/files/2019/07/New_component_flowchart.png)](https://coggle.it/diagram/WtUSrld3uAYZHsn-/t/new-ui-component/992b38cbe685d897b4aec6d0dd93cc4b47c06e0d4484eeb0d7d9a47fb2c48d94) + +## First steps to contributing + +Once you’re ready to contribute to WordPress Components, start by opening a GitHub issue. Include a detailed description in which you: + +- Explain the rationale +- Detail the intended behavior +- Clarify whether it’s a variation of an existing component, or a new asset +- Include mockups of any fidelity (optional) +- Include any inspirations from other products (optional) + +This issue will be the staging ground for the contribution and an opportunity for the community to weigh in with any suggestions. Reviewers can also check if there is overlap with an existing component, or if there is a more appropriate location for the component. +It’s encouraged to surface works-in-progress. If you’re not able to complete all of the parts yourself, someone in the community may be able to pick up where you left off. + +## Parts of a component contribution + +1. **Provide a rationale**: Explain how your component will add value to the system and the greater product ecosystem. Be sure to include any user experience and interaction descriptions. +2. **Create a design spec**: Create sizing and styling annotations for all aspects of the component. This spec should provide a developer with everything they need to create the design in code. +3. **Create a Figma component**: Any new components or changes to existing components will mirror the [WordPress Components Figma library](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=735%3A0), so we’ll need to update the Figma library and publish the changes. Please follow the [guidelines](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=746%3A38) for contributing to the Figma libraries. +4. **Provide usage documentation**: If the contribution adds additional behavior or expands a component’s features, we’ll need to document them with development and design guidelines. Read through existing component documentation for examples. +5. **Provide working code**: The component or enhancement must be built in React. See the [developer contribution guidelines](https://github.com/WordPress/gutenberg/blob/master/docs/contributors/develop.md). + +Remember, it’s unlikely that all parts will be done by one person. Someone in the community may be able to help. + +## Component refinement + +Before a component is published it will need to be fine-tuned: + +1. **Expand** to a minimally sufficient feature set. Resolve what features should be included in the component. +2. **Reduce** scope to omit contentious features. Review proposed features and prune unessential items lacking consensus. +3. **Quality assurance**: each contribution must be normalized into system standards. + +### Quality assurance + +To ensure quality, each component should be tested. The testing process should be done during the development of the component and before the component is published. + +- **Accessibility**: Has the design and implementation accounted for accessibility? Please use the [WordPress accessibility guidelines](https://make.wordpress.org/accessibility/handbook/best-practices/). +- **Visual quality**: Does the component apply visual style — color, typography, icons, space, borders, and more — using appropriate variables, and does it follow [visual guidelines](https://make.wordpress.org/design/handbook/design-guide/)? +- **Responsiveness**: Does it incorporate responsive display patterns and behaviors as needed? Is the component designed from a mobile-first perspective? Do all touch interactions work as expected? +- **Sufficient states & variations**: Does it cover all the necessary variations (primary, secondary, dense, etc.) and states (default, hover, active, disabled, loading, etc.), given the intended scope? +- **Content resilience**: Is each dynamic word or image element resilient to too much, too little, and no content at all, respectively? How long can labels be, and what happens when you run out of space? +- **Composability**: Does it fit well when placed next to or layered with other components to form a larger composition? +- **Functionality**: Do all behaviors function as expected? +- **Browser support**: Has the component visual quality and accuracy been assessed across Safari, Chrome, Firefox, IE, and other browsers across relevant devices? Please adhere to our [browser support requirements](https://github.com/WordPress/gutenberg/blob/master/packages/browserslist-config/index.js). +- **Documentation**: Ensure that the component has proper documentation for development, design, and accessibility. + +## Deprecation + +A component/feature may need deprecation if: + +- There’s a preferred alternative or it’s no longer in demand +- It’s no longer necessary +- It’s moved to a different location + +At no point does the deprecated component become unavailable. Instead, the commitment to support it stops. The following steps are needed to deprecate a component: + +1. Communicate intent via regular channels. + 1. Describe reasoning for deprecation. + 2. Decide on a timeline. +2. Ensure backwards compatibility to keep it available. +3. Clearly mark the component as deprecated in documentation and other channels. + + + From 0ed6a0b0ee8c3ad230756d9b67d860770cad1088 Mon Sep 17 00:00:00 2001 From: Dave Whitley Date: Thu, 1 Aug 2019 11:03:42 -0500 Subject: [PATCH 2/4] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Small tweaks to improve copy. Co-Authored-By: sarah ✈ semark --- packages/components/src/CONTRIBUTING.md | 26 +++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/packages/components/src/CONTRIBUTING.md b/packages/components/src/CONTRIBUTING.md index b8480994517a35..8e80606106fbb9 100644 --- a/packages/components/src/CONTRIBUTING.md +++ b/packages/components/src/CONTRIBUTING.md @@ -1,23 +1,25 @@ # Contributing components -These guidelines document how to contribute to components in the [`@wordpress/components`](https://www.npmjs.com/package/@wordpress/components) npm package, or “WordPress Components”. This can be addition, modification, or deprecation. +You can contribute by adding, modifying, or deprecating components, as well as helping with design, development, and documentation. ## Does it belong in the component library? -A component library should include what’s shared across many products and omit what’s not. Questions to help determine if a component should be added: +A component library should include components that are generic and flexible enough to work across a variety of products. It should include what’s shared across many products and omit what’s not. -- Is it relevant to other products/plugins? -- Is there overlap with any existing components? +To determine if a component should be added, ask yourself: + +- Could this component be used by other products/plugins? +- Does the new component overlap (in functionality or visual design) with any existing components? - How much will it cost to make and maintain? -- Can you articulate how the component should be used? +- Is there a clear use case requirement for the component, and can you articulate usage guidelines? Here’s a flowchart that can help determine if a new component is necessary: [![New component flowchart](https://wordpress.org/gutenberg/files/2019/07/New_component_flowchart.png)](https://coggle.it/diagram/WtUSrld3uAYZHsn-/t/new-ui-component/992b38cbe685d897b4aec6d0dd93cc4b47c06e0d4484eeb0d7d9a47fb2c48d94) -## First steps to contributing +## First steps -Once you’re ready to contribute to WordPress Components, start by opening a GitHub issue. Include a detailed description in which you: +If you have a component you'd like added or changed, start by opening a GitHub issue. Include a detailed description in which you: - Explain the rationale - Detail the intended behavior @@ -25,18 +27,18 @@ Once you’re ready to contribute to WordPress Components, start by opening a Gi - Include mockups of any fidelity (optional) - Include any inspirations from other products (optional) -This issue will be the staging ground for the contribution and an opportunity for the community to weigh in with any suggestions. Reviewers can also check if there is overlap with an existing component, or if there is a more appropriate location for the component. +This issue will be used to discuss the proposed changes and track progress. Reviewers start by discussing the proposal to determine if it's appropriate for WordPress Components. They can also check if there is overlap with an existing component, or if there is a more appropriate location for the component. It’s encouraged to surface works-in-progress. If you’re not able to complete all of the parts yourself, someone in the community may be able to pick up where you left off. ## Parts of a component contribution 1. **Provide a rationale**: Explain how your component will add value to the system and the greater product ecosystem. Be sure to include any user experience and interaction descriptions. 2. **Create a design spec**: Create sizing and styling annotations for all aspects of the component. This spec should provide a developer with everything they need to create the design in code. -3. **Create a Figma component**: Any new components or changes to existing components will mirror the [WordPress Components Figma library](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=735%3A0), so we’ll need to update the Figma library and publish the changes. Please follow the [guidelines](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=746%3A38) for contributing to the Figma libraries. -4. **Provide usage documentation**: If the contribution adds additional behavior or expands a component’s features, we’ll need to document them with development and design guidelines. Read through existing component documentation for examples. +3. **Create a Figma component**: Any new components or changes to existing components will be mirrored in the [WordPress Components Figma library](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=735%3A0), so we’ll need to update the Figma library and publish the changes. Please follow the [guidelines](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=746%3A38) for contributing to the Figma libraries. +4. **Draft documentation**: New components need development, design, and accessibility guidelines. Additionally, if your change adds additional behavior or expands a component’s features, those changes will need to be fully documented as well. Read through existing component documentation for examples. Start with a rough draft, and reviewers will help polish documentation. 5. **Provide working code**: The component or enhancement must be built in React. See the [developer contribution guidelines](https://github.com/WordPress/gutenberg/blob/master/docs/contributors/develop.md). -Remember, it’s unlikely that all parts will be done by one person. Someone in the community may be able to help. +Remember, it’s unlikely that all parts will be done by one person. Contribute where you can, and others will help. ## Component refinement @@ -50,7 +52,7 @@ Before a component is published it will need to be fine-tuned: To ensure quality, each component should be tested. The testing process should be done during the development of the component and before the component is published. -- **Accessibility**: Has the design and implementation accounted for accessibility? Please use the [WordPress accessibility guidelines](https://make.wordpress.org/accessibility/handbook/best-practices/). +- **Accessibility**: Has the design and implementation accounted for accessibility? Please use the [WordPress accessibility guidelines](https://make.wordpress.org/accessibility/handbook/best-practices/) and use the "Needs Accessibility Feedback" tag to get a review from the accessibility team. It's best to request a review early (at the documentation stage) in order to ensure the component is designed inclusively from the outset. - **Visual quality**: Does the component apply visual style — color, typography, icons, space, borders, and more — using appropriate variables, and does it follow [visual guidelines](https://make.wordpress.org/design/handbook/design-guide/)? - **Responsiveness**: Does it incorporate responsive display patterns and behaviors as needed? Is the component designed from a mobile-first perspective? Do all touch interactions work as expected? - **Sufficient states & variations**: Does it cover all the necessary variations (primary, secondary, dense, etc.) and states (default, hover, active, disabled, loading, etc.), given the intended scope? From 6c435f16219f200a3a64b1dbf56817486d513cd3 Mon Sep 17 00:00:00 2001 From: Dave Whitley Date: Thu, 1 Aug 2019 14:29:53 -0500 Subject: [PATCH 3/4] Copy tweaks --- packages/components/src/CONTRIBUTING.md | 46 +++++++++++-------------- 1 file changed, 21 insertions(+), 25 deletions(-) diff --git a/packages/components/src/CONTRIBUTING.md b/packages/components/src/CONTRIBUTING.md index 8e80606106fbb9..ea8f78533fe9d2 100644 --- a/packages/components/src/CONTRIBUTING.md +++ b/packages/components/src/CONTRIBUTING.md @@ -10,8 +10,8 @@ To determine if a component should be added, ask yourself: - Could this component be used by other products/plugins? - Does the new component overlap (in functionality or visual design) with any existing components? -- How much will it cost to make and maintain? -- Is there a clear use case requirement for the component, and can you articulate usage guidelines? +- How much effort will be required to make and maintain? +- Is there a clear purpose for the component? Here’s a flowchart that can help determine if a new component is necessary: @@ -27,16 +27,19 @@ If you have a component you'd like added or changed, start by opening a GitHub i - Include mockups of any fidelity (optional) - Include any inspirations from other products (optional) -This issue will be used to discuss the proposed changes and track progress. Reviewers start by discussing the proposal to determine if it's appropriate for WordPress Components. They can also check if there is overlap with an existing component, or if there is a more appropriate location for the component. +This issue will be used to discuss the proposed changes and track progress. Reviewers start by discussing the proposal to determine if it's appropriate for WordPress Components, or if there's overlap with an existing component. + It’s encouraged to surface works-in-progress. If you’re not able to complete all of the parts yourself, someone in the community may be able to pick up where you left off. -## Parts of a component contribution +## Next steps + +Once the team has discussed and approved the change, it's time to start implementing it. 1. **Provide a rationale**: Explain how your component will add value to the system and the greater product ecosystem. Be sure to include any user experience and interaction descriptions. -2. **Create a design spec**: Create sizing and styling annotations for all aspects of the component. This spec should provide a developer with everything they need to create the design in code. -3. **Create a Figma component**: Any new components or changes to existing components will be mirrored in the [WordPress Components Figma library](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=735%3A0), so we’ll need to update the Figma library and publish the changes. Please follow the [guidelines](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=746%3A38) for contributing to the Figma libraries. -4. **Draft documentation**: New components need development, design, and accessibility guidelines. Additionally, if your change adds additional behavior or expands a component’s features, those changes will need to be fully documented as well. Read through existing component documentation for examples. Start with a rough draft, and reviewers will help polish documentation. -5. **Provide working code**: The component or enhancement must be built in React. See the [developer contribution guidelines](https://github.com/WordPress/gutenberg/blob/master/docs/contributors/develop.md). +2. **Draft documentation**: New components need development, design, and accessibility guidelines. Additionally, if your change adds additional behavior or expands a component’s features, those changes will need to be fully documented as well. Read through existing component documentation for examples. Start with a rough draft, and reviewers will help polish documentation. +3. **Provide working code**: The component or enhancement must be built in React. See the [developer contribution guidelines](https://github.com/WordPress/gutenberg/blob/master/docs/contributors/develop.md). +4. **Create a design spec**: Create sizing and styling annotations for all aspects of the component. This spec should provide a developer with everything they need to create the design in code. [Figma automatically does this for you](https://help.figma.com/article/32-developer-handoff). +5. **Create a Figma component**: Any new components or changes to existing components will be mirrored in the [WordPress Components Figma library](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=735%3A0), so we’ll need to update the Figma library and publish the changes. Please follow the [guidelines](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=746%3A38) for contributing to the Figma libraries. Remember, it’s unlikely that all parts will be done by one person. Contribute where you can, and others will help. @@ -44,39 +47,32 @@ Remember, it’s unlikely that all parts will be done by one person. Contribute Before a component is published it will need to be fine-tuned: -1. **Expand** to a minimally sufficient feature set. Resolve what features should be included in the component. -2. **Reduce** scope to omit contentious features. Review proposed features and prune unessential items lacking consensus. -3. **Quality assurance**: each contribution must be normalized into system standards. +1. **Expand** the features of the component to a minimum. Agree on what features should be included. +2. **Reduce** scope and leave off features lacking consensus. +3. **Quality assurance**: each contribution must adhere to system standards. ### Quality assurance To ensure quality, each component should be tested. The testing process should be done during the development of the component and before the component is published. -- **Accessibility**: Has the design and implementation accounted for accessibility? Please use the [WordPress accessibility guidelines](https://make.wordpress.org/accessibility/handbook/best-practices/) and use the "Needs Accessibility Feedback" tag to get a review from the accessibility team. It's best to request a review early (at the documentation stage) in order to ensure the component is designed inclusively from the outset. -- **Visual quality**: Does the component apply visual style — color, typography, icons, space, borders, and more — using appropriate variables, and does it follow [visual guidelines](https://make.wordpress.org/design/handbook/design-guide/)? -- **Responsiveness**: Does it incorporate responsive display patterns and behaviors as needed? Is the component designed from a mobile-first perspective? Do all touch interactions work as expected? +- **Accessibility**: Has the design and implementation accounted for accessibility? Please use the [WordPress accessibility guidelines](https://make.wordpress.org/accessibility/handbook/best-practices/). You must use the "Needs Accessibility Feedback" label and get a review from the accessibility team. It's best to request a review early (at the documentation stage) in order to ensure the component is designed inclusively from the outset. +- **Visual quality**: Does the component apply visual style — color, typography, icons, space, borders, and more — using appropriate variables, and does it follow [visual guidelines](https://make.wordpress.org/design/handbook/design-guide/)? You must use the "Needs Design Feedback" label and get a review from the design team. +- **Documentation**: Ensure that the component has proper documentation for development, design, and accessibility. - **Sufficient states & variations**: Does it cover all the necessary variations (primary, secondary, dense, etc.) and states (default, hover, active, disabled, loading, etc.), given the intended scope? +- **Functionality**: Do all behaviors function as expected? +- **Responsiveness**: Does it incorporate responsive display patterns and behaviors as needed? Is the component designed from a mobile-first perspective? Do all touch interactions work as expected? - **Content resilience**: Is each dynamic word or image element resilient to too much, too little, and no content at all, respectively? How long can labels be, and what happens when you run out of space? - **Composability**: Does it fit well when placed next to or layered with other components to form a larger composition? -- **Functionality**: Do all behaviors function as expected? - **Browser support**: Has the component visual quality and accuracy been assessed across Safari, Chrome, Firefox, IE, and other browsers across relevant devices? Please adhere to our [browser support requirements](https://github.com/WordPress/gutenberg/blob/master/packages/browserslist-config/index.js). -- **Documentation**: Ensure that the component has proper documentation for development, design, and accessibility. ## Deprecation -A component/feature may need deprecation if: - -- There’s a preferred alternative or it’s no longer in demand -- It’s no longer necessary -- It’s moved to a different location +A component or prop may need deprecation if it's renamed or removed. -At no point does the deprecated component become unavailable. Instead, the commitment to support it stops. The following steps are needed to deprecate a component: +At no point does the deprecated component/prop become unavailable. Instead, the commitment to support it stops. The following steps are needed to deprecate a component: 1. Communicate intent via regular channels. 1. Describe reasoning for deprecation. 2. Decide on a timeline. 2. Ensure backwards compatibility to keep it available. 3. Clearly mark the component as deprecated in documentation and other channels. - - - From fe8c92be8d02542392c182937c8bc3f330e6b634 Mon Sep 17 00:00:00 2001 From: Dave Whitley Date: Thu, 1 Aug 2019 14:41:25 -0500 Subject: [PATCH 4/4] Simplify language --- packages/components/src/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/components/src/CONTRIBUTING.md b/packages/components/src/CONTRIBUTING.md index ea8f78533fe9d2..8acfc7811cf81b 100644 --- a/packages/components/src/CONTRIBUTING.md +++ b/packages/components/src/CONTRIBUTING.md @@ -58,12 +58,12 @@ To ensure quality, each component should be tested. The testing process should b - **Accessibility**: Has the design and implementation accounted for accessibility? Please use the [WordPress accessibility guidelines](https://make.wordpress.org/accessibility/handbook/best-practices/). You must use the "Needs Accessibility Feedback" label and get a review from the accessibility team. It's best to request a review early (at the documentation stage) in order to ensure the component is designed inclusively from the outset. - **Visual quality**: Does the component apply visual style — color, typography, icons, space, borders, and more — using appropriate variables, and does it follow [visual guidelines](https://make.wordpress.org/design/handbook/design-guide/)? You must use the "Needs Design Feedback" label and get a review from the design team. - **Documentation**: Ensure that the component has proper documentation for development, design, and accessibility. -- **Sufficient states & variations**: Does it cover all the necessary variations (primary, secondary, dense, etc.) and states (default, hover, active, disabled, loading, etc.), given the intended scope? +- **Sufficient states & variations**: Does it cover all the necessary variations (primary, secondary, dense, etc.) and states (default, hover, active, disabled, loading, etc.), within the intended scope? - **Functionality**: Do all behaviors function as expected? -- **Responsiveness**: Does it incorporate responsive display patterns and behaviors as needed? Is the component designed from a mobile-first perspective? Do all touch interactions work as expected? +- **Responsiveness**: Does it incorporate responsive behaviors as needed? Is the component designed from a mobile-first perspective? Do all touch interactions work as expected? - **Content resilience**: Is each dynamic word or image element resilient to too much, too little, and no content at all, respectively? How long can labels be, and what happens when you run out of space? - **Composability**: Does it fit well when placed next to or layered with other components to form a larger composition? -- **Browser support**: Has the component visual quality and accuracy been assessed across Safari, Chrome, Firefox, IE, and other browsers across relevant devices? Please adhere to our [browser support requirements](https://github.com/WordPress/gutenberg/blob/master/packages/browserslist-config/index.js). +- **Browser support**: Has the component visual quality and accuracy been checked across Safari, Chrome, Firefox, IE, etc? Please adhere to our [browser support requirements](https://github.com/WordPress/gutenberg/blob/master/packages/browserslist-config/index.js). ## Deprecation