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.

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

Documentation: adding new components #16845

Merged
merged 4 commits into from Aug 12, 2019

Conversation

@davewhitley
Copy link
Contributor

commented Jul 31, 2019

Description

This is a first attempt at including some sort of guidance for adding/proposing/suggesting new components to the wordpress/components npm package. I pulled documentation from several different sources.

We need guidelines for:

  • Determining if a component should be added
  • Proposing a component
  • Testing the component
  • Deprecating components

It's not comprehensive, but I expect this document to evolve as we add more components.

cc @sarahmonster @karmatosed

Add component contribution guidelines

## Deprecation

A component/feature may need deprecation if:

This comment has been minimized.

Copy link
@gziolo

gziolo Aug 1, 2019

Member

We should emphasize that this applies not only to components but also to their props, whenever we add a new one, rename or remove. This should be reflected in the docs but at the same time we should ensure that old code still works as close as possible to what was before and deprecation warnings are outputted to the Web Console encouraging to use the new recommended version.

This comment has been minimized.

Copy link
@youknowriad

youknowriad Aug 1, 2019

Contributor

I wonder if this section belongs to this document, since this is generic and applies to any public API of the project. (A backward compatibility policy document)

This comment has been minimized.

Copy link
@gziolo

gziolo Aug 1, 2019

Member

From my experience, it doesn't harm to repeat it a couple of times in our docs 😃

This comment has been minimized.

Copy link
@sarahmonster

sarahmonster Aug 1, 2019

Member

I have no idea where our backward compatibility policy document is—linking to it here might be a good approach, but it's definitely helpful being as explicit as possible about our approach here, specifically with reference to how that works for components.

This comment has been minimized.

Copy link
@davewhitley

davewhitley Aug 1, 2019

Author Contributor

I agree there are some component specific things that can be included here.

Copy link
Member

left a comment

Overall this looks 💯. Yay for contribution guidelines! I've made some (mostly nitpicky, fairy minor) changes and suggestions.

The three biggest changes I'd suggest are:

  • Simplifying language wherever possible to be more concrete and less abstract (including examples helps a lot) and to make it a bit friendlier to contributors whose first language isn't English.
  • Lead with documentation (or at least draft documentation) rather than with visual designs, to encourage people to think first about usage patterns, functionality, and semantics.
  • Make design, development, and accessibility reviews clear blockers to merging new components.
packages/components/src/CONTRIBUTING.md Outdated Show resolved Hide resolved
packages/components/src/CONTRIBUTING.md Show resolved Hide resolved
packages/components/src/CONTRIBUTING.md Outdated Show resolved Hide resolved
packages/components/src/CONTRIBUTING.md Outdated Show resolved Hide resolved
packages/components/src/CONTRIBUTING.md Outdated Show resolved Hide resolved

## Deprecation

A component/feature may need deprecation if:

This comment has been minimized.

Copy link
@sarahmonster

sarahmonster Aug 1, 2019

Member

I have no idea where our backward compatibility policy document is—linking to it here might be a good approach, but it's definitely helpful being as explicit as possible about our approach here, specifically with reference to how that works for components.

packages/components/src/CONTRIBUTING.md Outdated Show resolved Hide resolved
packages/components/src/CONTRIBUTING.md Show resolved Hide resolved
packages/components/src/CONTRIBUTING.md Show resolved Hide resolved
packages/components/src/CONTRIBUTING.md Outdated Show resolved Hide resolved
Small tweaks to improve copy.

Co-Authored-By: sarah ✈ semark <sarah@triggersandsparks.com>
@@ -0,0 +1,82 @@
# Contributing components

This comment has been minimized.

Copy link
@mtias

mtias Aug 1, 2019

Contributor

Maybe "Contributing to WordPress Interface Components"?

@davewhitley

This comment has been minimized.

Copy link
Contributor Author

commented Aug 1, 2019

Thanks for the reviews everyone! I've gathered some non-blocking issues that need some next steps:

  • Create documentation/template for writing component guidelines
  • Better flowchart
  • Expand on the Deprecation section with specifics (communication channels, actual deprecation steps, etc.)

Can someone more knowledgeable that me please handle the last one in another PR?

@davewhitley

This comment has been minimized.

Copy link
Contributor Author

commented Aug 9, 2019

@sarahmonster mind giving this another look? I think it's ready to go and other improvements could be made in following PRs.

Copy link
Member

left a comment

This looks good to me. Thanks for the changes! 🚢

@mkaz mkaz merged commit 8bbe76c into master Aug 12, 2019
1 of 7 checks passed
1 of 7 checks passed
Filter opened Filter opened
Details
Filter opened Filter opened
Details
Filter opened Filter opened
Details
Filter opened Filter opened
Details
Milestone It Milestone It
Details
Milestone It Milestone It
Details
Travis CI - Pull Request Build Passed
Details
@mkaz mkaz deleted the add/component-contribution-guidelines branch Aug 12, 2019
gziolo added a commit that referenced this pull request Aug 29, 2019
* Initial commit

Add component contribution guidelines

* Apply suggestions from code review

Small tweaks to improve copy.

Co-Authored-By: sarah ✈ semark <sarah@triggersandsparks.com>

* Copy tweaks

* Simplify language
gziolo added a commit that referenced this pull request Aug 29, 2019
* Initial commit

Add component contribution guidelines

* Apply suggestions from code review

Small tweaks to improve copy.

Co-Authored-By: sarah ✈ semark <sarah@triggersandsparks.com>

* Copy tweaks

* Simplify language
dd32 pushed a commit to dd32/gutenberg that referenced this pull request Sep 27, 2019
* Initial commit

Add component contribution guidelines

* Apply suggestions from code review

Small tweaks to improve copy.

Co-Authored-By: sarah ✈ semark <sarah@triggersandsparks.com>

* Copy tweaks

* Simplify language
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.