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.

Sign up for GitHub

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

Jump to bottom

[docs] What's the lab about? #19611

Merged
merged 5 commits into from
Feb 10, 2020
Merged

[docs] What's the lab about? #19611

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f9dadb6
[docs] Add differences between lab and core components
jcafiero Feb 7, 2020
01ff0df
[chore] remove whitespace
jcafiero Feb 7, 2020
9f289ea
[chore] remove duplicate documentation
jcafiero Feb 7, 2020
23f590b
Apply suggestions from code review
jcafiero Feb 10, 2020
18d4337
Update about-the-lab.md
oliviertassinari Feb 10, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/src/pages/components/about-the-lab/about-the-lab.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,18 @@

<p class="description">This package hosts the incubator components that are not yet ready to move to the core.</p>

The main difference between the lab and the core is how the components are versioned. Having a separate lab package allows us to release breaking changes when necessary while the core package follows a [slower-moving policy](https://material-ui.com/versions/#release-frequency).

As developers use and test the components and report issues, the maintainers learn more about shortcomings of the components: missing features, accessibility issues, bugs, API design, etc. The older and more used a component is, the less likely it is that new issues will be found and subsequently need to introduce breaking changes.

For a component to be ready to move to the core, the following criteria are considered:
* It needs to be **used**. The Material-UI team uses Google Analytics stats among other metrics to evaluate the usage of each component. A lab component with low usage either means that it isn't fully working yet or that there is a low demand for it.
* It needs to match the **code quality** of the core components. It doesn't have to be perfect to be a part of the core, but the component should be reliable enough that developers can depend on it.
* Each component needs **type definitions**. It is not currently required that a lab component is typed, but it would need to be typed to move to the core.
* Requires good **test coverage**. Some of the lab components don't currently have comprehensive tests.
* Can it be used as **leverage** to incentivize users to upgrade to the latest major release? The less fragmented the community is, the better.
* It needs to have a low probability of a **breaking change** in the short/medium future. For instance, if it needs a new feature that will likely require a breaking change, it may be preferable to delay its promotion to the core.

## Installation

Install the package in your project directory with:
Expand Down