| Stage | Status |
|---|---|
| Approved | ✅ |
| Adopted | 🚧 |
Drafts were introduced in ADR-006 as a way of creating components outside of the root bundle of @primer/react. This helps us create, test and maintain multiple versions of the same component in parallel.
Example:
// default version of component exported from root of package
import {UnderlineNav} from '@primer/react'
// new version of component exported from /drafts
import {UnderlineNav} from '@primer/react/drafts'We have also used this method for components that are still a work in progress and we don't want developers to start using them in production without collaborating with us first.
Example:
// this component only exists in drafts and not in the roof of the package
import {TreeView} from '@primer/react/drafts'The reason we do not use experimental label for these components is because drafts conveys a different message than maturity on the component lifecycle.
A draft component can be further along on the component lifecycle than experimental, but still not be the recommended version of the component until the next major release (to plan breaking changes better). For example, at the time of writing, the new UnderlineNav2 in drafts has been reviewed for accessibility and is almost at Beta maturity. We can call it a draft component with beta maturity.
This is very confusing. While the above separation is useful for maintainers of primer, it is less useful to consumers.
- Consumers of primer are often confused to not find
draftmaturity on the component lifecycle. - It is similar to
experimentallabel in the most important characteristic to consumers - The component is not ready for production usage.
We should drop the draft label and use experimental instead.
While not completely accurate (UnderlineNav2 is much more polished than experimental maturity), the lack of confusion makes it a good trade-off.
Fine-grained information about component maturity, useful for maintainers, is also communicated by the status checklist in the component documentation.
We should create a new parallel import path for @primer/react/experimental.
// new version of component exported from /experimental
- import { UnderlineNav } from '@primer/react/drafts'
+ import { UnderlineNav } from '@primer/react/experimental'We would need to keep @primer/react/drafts in the short term as well for backwards compatibility.