ADR: Parallel drafts track & plan for deprecated components

contributor-docs/adrs/adr-005.md

@@ -0,0 +1,71 @@
+# ADR 5: Parallel experimental track & plan for deprecated components
+
+## Status
+
+Proposed
+
+## Context
+
+As we work on maturity of our components, we will sometimes need to build components in a parallel track/bundle without breaking existing components. Eventually, the new components would replace the old ones in the main bundle.
+
+## Here are the 3 proposed stages:
+
+### Stage 1
+
+Start new component outside the main bundle. Folks who want to try it, need to explicitly import it from the `drafts` bundle.
+
+`import { ActionMenu} from '@primer/react/drafts'`
+
+The contract with consumers is - you are opting into a rewrite of the old component that might not cover all the cases of the old component yet. If you are using both the old and new version of the component in different pages, you are paying some additional bundlesize cost.
+
+Note: If it is a 1:1 replacement, it's useful to keep the component name the same for consumers. Internally, we would want to call the filename `ActionMenu2.tsx` and call it `ActionMenu v2` in the docs.
+
+### Stage 2
+
+After we have the confidence that this component is better than the old version of it, we swap the components and move the old component out of the main bundle.
+
+This is a breaking change! It’s recommended that you start using the new component, but if you’d like to push that effort to the future, we give you an easy way out -
+
+`import { ActionMenu } from '@primer/react/deprecated'`
+
+The deprecated component does not accept new features requests.
+
+Reason: Because we have a single bundle for all components, you can not pick the components you want to upgrade. This can results in additional unrelated work.
+
+### Stage 3
+
+After 3 months of living in the `deprecated` bundle, a component is retired/deleted from the codebase.
+
+At this point, consumers are expected to plan migration work.
+
+## Suggested changes:
+
+We should detangle "drafts" from component lifecycle.
+
+"Drafts components" should not be collocated with "main bundle" components in the documentation or status page. They should have their own section because they are not recommended as an alternative yet.
+
+## Relevant components:
+
+Deprecated in favor of Box, ready for stage 2:
+
+1. BorderBox
+2. Flex
+3. Grid
+4. Position
+5. SelectMenu
+
+Replaced with newer components
+
+6. Dialog - replaced with Dialog2, ready for stage 2
+7. Dialog2 - ready for Stage 2 with rename, already in main bundle
+8. Dropdown - replaced with DropdownMenu, ready for stage 2
+9. SelectPanel - unclear if it should be renamed, already in main bundle
+
+Future deprecations, replaced with newer components
+
+10. ActionList - replaced with ActionList2, need to plan for stage 2
+11. ActionList v2 - in drafts bundle, need to plan for stage 2
+12. ActionMenu - replaced with ActionList2, need to plan for stage 2
+13. ActionList v2 - in drafts bundle, need to plan for stage 2
+14. Button - replaced with Button v2, need to plan for stage 2
+15. Button v2 - in drafts bundle, need to plan for stage 2