[RFC] docs(contribution): community components model #3769
Conversation
|
Deploy preview for the-carbon-components ready! Built with commit 238fff7 https://deploy-preview-3769--the-carbon-components.netlify.com |
|
Deploy preview for carbon-components-react ready! Built with commit 238fff7 https://deploy-preview-3769--carbon-components-react.netlify.com |
|
Deploy preview for carbon-elements ready! Built with commit 238fff7 |
| **How do I include my design assets in the component package?** | ||
|
|
||
| If you're contributing design, you will add your sketch files to the community | ||
| components [box folder](url here). In the monorepo, we will include the |
There was a problem hiding this comment.
has this folder been created yet?
There was a problem hiding this comment.
No. We haven't created any assets for this. We wanted to get feedback on the model first.
There was a problem hiding this comment.
ok got it, I assumed we had some existing from our previous addons
| in the monorepo. Reaching 100% completeness means meeting all of the design and | ||
| development guidelines on this list. | ||
|
|
||
| **Basic (always required)** |
There was a problem hiding this comment.
For communities that have more rigorus requirements would be we be able to extend the this list for our specific package? (regulated environments for example have more testing/documentation that is required).
There was a problem hiding this comment.
Since the criteria live with the component, regulated environments would be able to use (or not use) components that meet their unique criteria.
There was a problem hiding this comment.
To add to what Vince said, components can definitely have more design and technical specs than what's on this list (i.e. if you support RTL) but these are objective completeness measures based on what Carbon supports. We don't want to require more rigorous specs if it's not something that we don't support in our own components, but we won't stop teams from implementing them on their own. @elizabethsjudd
|
|
||
| ### What are community components? | ||
|
|
||
| Community Components is our new library of custom components contributed by you. |
There was a problem hiding this comment.
WH has a a group of Carbon components that are built in Handlebars that are exportable and re-useable... would that live in the community components under a single package for "handlebars"? or would that be something that would still want to be in the core library since they are duplicate components from what is in core?
There was a problem hiding this comment.
The idea is that any components that don't already exist in our core library would live in community components. Whether they are variations of our core components (i.e. a component with a new feature that we don't have) or a completely different component that we don't have, we would want them to live in community components @elizabethsjudd
| - [`@carbon/layout`](https://github.com/carbon-design-system/carbon/tree/master/packages/layout) | ||
| - [`@carbon/motion`](https://github.com/carbon-design-system/carbon/tree/master/packages/motion) | ||
| - [`@carbon/themes`](https://github.com/carbon-design-system/carbon/tree/master/packages/themes) | ||
| - [`@carbon/icons-react`](https://github.com/carbon-design-system/carbon/tree/master/packages/icons-react) |
There was a problem hiding this comment.
isn't there other @carbon/icons-* packages as well? (WH specifically uses the handlebars one)
There was a problem hiding this comment.
There are a few other packages in general. We've listed some of our main ones here, but included a link to all our packages below it.
| ### What if I want to contribute a new feature or custom component? | ||
|
|
||
| If you're contributing to Carbon Components, we will only accept bug fixes. If | ||
| you want to contribute a custom component, new feature, or a variation of an |
There was a problem hiding this comment.
A lot of times to add a feature/variation of a core component it's duplicating a lot of work from the core repo to achieve the desired outcome vs just making the core component more flexible. Would there be a way to denote that a variation in core is owned by someone outside of the core team. Examples we have: required modals that remove the x on the modal, overflow menus that have headings within the list, etc.
There was a problem hiding this comment.
We realize that there are variations of our components and it would be easier for the contributors to just work in our source code but there are 2 main reasons that we don't want that:
- We don't want our developers to have to become familiar or deal with more code. Even if we said that a component variation was maintained by another person not on Carbon, that code would still be something that we have to become familiar with, approve, etc. We'd also have to deal with potential bugs from a new variation that might affect anything we're doing with that component. Etc.
- We don't want to approve features without extensive design research behind it.
This feeds into community-component-to-core path. We would only consider variations of components eventually moving into core/being maintained by us after we see that there's been thorough research, maintenance, use/need for the component.
Essentially what we don't want to do is create more work for our designers and developers until we've seen evidence that this should live in core Carbon.
| The diagram above illustrates one way we could implement this vision for | ||
| community contribution. In this model we would need both a Core Carbon and a | ||
| Community monorepo. The Community repo would consume packages from Core Carbon | ||
| repo and both monorepos would need to run on the same spec model (this has not |
There was a problem hiding this comment.
if they are running the same spec across repos but community components that are variations on an existing component would require either duplicate specs OR the core specs would need to be updated to allow the flexibility. (see previous comment about how variants in the separate repo would also be troublesome/non-DRY)
| @@ -0,0 +1,3 @@ | |||
| # Patterns contributions | |||
|
|
|||
| Patterns contribution guidelines coming soon! | |||
There was a problem hiding this comment.
The IBM.com Library team has a ton of patterns work on our roadmap very soon, as this is a huge need for IBM.com adopters (React/Vanilla). Our current plan is creating a patterns package in our monorepo. We should sync up to see how much this will align with what Carbon team has in mind.
cc: @photodow @oliviaflory @larahanlon2
There was a problem hiding this comment.
WH also has a ton of Pattern work going on as well @AT-public @vincentsnagg @janedepgen
| practices and proper commit messages. | ||
| 3. **Issue:** Check repo for an _existing_ issue related to your contribution | ||
| first. If none exist, open a new issue. | ||
| 4. **Package directory:** Once you open an issue, we will review that you have a |
There was a problem hiding this comment.
Out of curiosity, what would the turn around time be on creating the set up for contributions.
Besides a duplicate name would there be any reason why an issue would be denied?
There was a problem hiding this comment.
I have some technical questions around the community components mono repo approach:
- Will all of the community components be packaged and released together by framework? Does endorsement play into this?
- Will all of the community components share a stylesheet? How do we prevent naming collisions in those styles?
- What if a component meets certain (non-automated) criteria but either the criteria or the component changes so this isn't true any more?
| _If we're not required to meet any of the guidelines, why would we want to | ||
| create more work for ourselves by trying to meet most of them?_ | ||
|
|
||
| Good question. Carbon will be endorsing components that meet 80% or more of |
There was a problem hiding this comment.
This seems kind of arbitrary. I get having a loose 'base' requirement, but by this standard we'd endorse a component as being the same design and development level as a core component with the following criteria:
- fails all 3 accessibility levels
- is built with v9
- only supports Chrome.
- no interactive states
| - [ ] Semantic HTML | ||
| - [ ] Code documentation (props, class/selectors) | ||
| - [ ] Include different states (hover, focus, disabled) | ||
| - [ ] Unit testing |
There was a problem hiding this comment.
What will the Continuous Integration process be? This has potential to be a very large monorepo with a lot of disparate technologies. Is it possible to have a separate CI process on a per-package basis?
There was a problem hiding this comment.
If there is not separate processes, what happens if an un-related package is failing CI - will the cross-package CI system be merge-blocking for all packages?
| - [ ] SASS | ||
| - [ ] Using Carbon design tokens (color, type, motion, spacing) | ||
| - [ ] `#{$prefix}` class naming | ||
| - [ ] Semantic HTML |
There was a problem hiding this comment.
Will this be tested for using the free tools from W3?
| - [ ] Using Carbon design tokens (color, type, motion, spacing) | ||
| - [ ] `#{$prefix}` class naming | ||
| - [ ] Semantic HTML | ||
| - [ ] Code documentation (props, class/selectors) |
There was a problem hiding this comment.
Can these be created via an auto-generated process as part of CI?
| - [ ] Using IBM icons | ||
| - [ ] Using IBM grid & layout guidance | ||
| - [ ] Design in all 4 color themes | ||
| - [ ] Satisfy basic accessibility contrast requirements (text readability 4.5:1, |
There was a problem hiding this comment.
Will there be automated a11y testing in the community repo?
| - [ ] Semantic HTML | ||
| - [ ] Code documentation (props, class/selectors) | ||
| - [ ] Include different states (hover, focus, disabled) | ||
| - [ ] Unit testing |
There was a problem hiding this comment.
If there is not separate processes, what happens if an un-related package is failing CI - will the cross-package CI system be merge-blocking for all packages?
| - [ ] Satisfy basic accessibility contrast requirements (text readability 4.5:1, | ||
| info graphics 3:1) | ||
|
|
||
| **Code** |
There was a problem hiding this comment.
What if the community contribution is an add-on feature of an existing component? For instance, if there was a feature that Carbon didn't want to add to a Core component? Will it be possible to create a component directory that imports and builds upon a Core component, yet retains it's naming? As a super basic for instance, what if a team needed a yellow Tag? This would seem like overkill to create a completely new component. Could something like this happen:
Carbon-Community/packages/tag
docs: use core/tag docs and addyellowto them (could be automated via JSDoc)tests: use core/tag/tests, adding a test for theyellowtagstyles: import core/tag/*.scss addingyellowtag styleHTML: this community component would not need it's own HTML - it would use thecoreone because there are no HTML differences
End user:
Imports Carbon-Community/packages/tag, receives the entirety of the Tag component
|
|
||
| **Frameworks** | ||
|
|
||
| - [ ] Vanilla JS |
There was a problem hiding this comment.
can one community-component contain multiple framework implementations within it?
| - [ ] Angular | ||
| - [ ] Vue | ||
|
|
||
| **Browser support** |
There was a problem hiding this comment.
Will there be screen-reader support guidelines?
|
|
||
| 1. **Contributor License Agreement:** Before you can contribute any code, we | ||
| need you to sign a Contributor License Agreement (CLA). | ||
| 2. **Development environment:** If you haven't already, fork and clone the |
There was a problem hiding this comment.
Will Carbon be supplying dev environment functionality? Test runners, sass processing, live-reload dev server, etc?
Would these be tools which we could set up as needed for a package?
Would this functionality be part of setting up the package directory done by Carbon?
|
@jnm2377 do we want to separate out the COC into a separate PR to get merged in? Following up on this, is there anything that you need to move forward with this or should we close and regroup with the feedback received? |
|
Gonna close this as we're cleaning up our PRs, feel free to re-open! |
No description provided.