diff --git a/docs/experimental-code.md b/docs/experimental-code.md new file mode 100644 index 000000000000..e57d1f98f5c2 --- /dev/null +++ b/docs/experimental-code.md @@ -0,0 +1,96 @@ +# Experimental Code + +The team occasionally will author code, or accept contributions, that is +considered experimental or unstable. The goal for this code is to ship it as +unstable for sponsor groups to leverage. During this time, the team can get +feedback around what is working and what does not work so that changes can be +made before an official release. + +This code should be treated as experimental and will break between release +versions for the package that it is being imported from. + +- The API is not fixed, and is likely to change +- The API is not bound by semver +- The component export may change, be renamed, or removed in the future without + warning + +## Naming experimental code + +For experimental or unstable code, we use the `unstable_` prefix. For example: + +```js +// An unstable method +function unstable_layout() { + // ... +} + +// An unstable variable +const unstable_meta = { + // ... +}; + +// An unstable component will retain its name, specifically for things like +// the rules of hooks plugin which depend on the correct casing of the name +function Pagination(props) { + // ... +} + +// However, when we export the component we will export it with the `unstable_` +// prefix. (Similar to React.unstable_Suspense, React.unstable_Profiler) +export { default as unstable_Pagination } from './components/Pagination'; +``` + +For teams using these features, they will need to import the functionality by +using the `unstable_` prefix. For example: + +```jsx +import { unstable_Pagination as Pagination } from 'carbon-components-react'; +``` + +## Experimental status + +Components with the prefix `unstable_`, eg, `unstable_ComponentName` are +experimental + +Within the storybook these components' stories are prefixed, and may include a +notice regarding specific instability or experimental status. + +## Moving to stable + +Over time it becomes apparent an experimental API has stabilized and suits the +needs of most users. When there hasn't been much movement on a component, it can +be marked to be moved from "experimental" status to be "stable" by opening a new +issue requesting it be moved to stable. + +The following criteria need to be met when moving a component from experimental +to stable: + +- [ ] All files have a copyright banner +- [ ] All components exported in `src/index.js` and should not be `unstable_` + prefixed +- [ ] Component has a label in the github repository +- [ ] Component should be documented on the website + - [ ] Component should have a usage, style, and code tab + - [ ] Component may have a component demo +- [ ] For each component exported: + - [ ] Component is written as a function declaration or uses `forwardRef` + - [ ] Component has `propTypes` defined + - [ ] Each prop type has a comment (used in storybook) + - [ ] Prop types are as specific as needed, prefer `PropTypes.shape` over + `PropTypes.object` if possible + - [ ] Default props are listed as default args in the function definition (not + in defaultProps) + - [ ] Note: default props should be stable, in other words props like + `onClick = () => {}` can cause re-renders since the function identity + is not stable + - [ ] Component has a story in `.stories.js` + - [ ] Component has an mdx document that follows our outline + - [ ] mdx document coverages at least common use-cases and provides a prop + table + - [ ] Stories cover at least common use-cases + - [ ] Stories may include a `Playground` story for controls + - [ ] Stories should mirror intended usage of the component + - [ ] Component has unit/integration tests written in RTL for testing the + component API + - [ ] Component is tested via VRT for at least the initial render state + - [ ] Component is tested via AVT for at least the initial render state diff --git a/docs/style.md b/docs/style.md index ec96357bbb1b..0e0889dd3188 100644 --- a/docs/style.md +++ b/docs/style.md @@ -499,45 +499,7 @@ the function as `handleOnClick`. #### Naming experimental code -The team occasionally will author code, or accept contributions, that is -considered experimental or unstable. The goal for this code is to ship it as -unstable for sponsor groups to leverage. During this time, the team can get -feedback around what is working and what does not work so that changes can be -made before an official release. - -For experimental or unstable code, we use the `unstable_` prefix. For example: - -```js -// An unstable method -function unstable_layout() { - // ... -} - -// An unstable variable -const unstable_meta = { - // ... -}; - -// An unstable component will retain its name, specifically for things like -// the rules of hooks plugin which depend on the correct casing of the name -function Pagination(props) { - // ... -} - -// However, when we export the component we will export it with the `unstable_` -// prefix. (Similar to React.unstable_Suspense, React.unstable_Profiler) -export { default as unstable_Pagination } from './components/Pagination'; -``` - -For teams using these features, they will need to import the functionality by -using the `unstable_` prefix. For example: - -```jsx -import { unstable_Pagination as Pagination } from 'carbon-components-react'; -``` - -This code should be treated as experimental and will break between release -versions for the package that it is being imported from. +See [Experimental Code](./experimental-code.md#naming-experimental-code); ### Testing