From d8217154ccdd05ae28a5f4f5cdb7cc580537dd6c Mon Sep 17 00:00:00 2001 From: Elizabeth Craig Date: Tue, 2 Feb 2021 11:59:58 -0800 Subject: [PATCH 1/3] Add RFC for communicating converged package status --- .../communicating-convergence-status.md | 142 ++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 rfcs/packaging/communicating-convergence-status.md diff --git a/rfcs/packaging/communicating-convergence-status.md b/rfcs/packaging/communicating-convergence-status.md new file mode 100644 index 0000000000000..d3be728d487f6 --- /dev/null +++ b/rfcs/packaging/communicating-convergence-status.md @@ -0,0 +1,142 @@ +# RFC: Communicating convergence status for `@fluentui/*` packages (and related code moves) + +**Note that this RFC focuses solely on near-term steps to clearly communicate to consumers which of our packages are old vs. converged. It's focused primarily on v7/8 and converged packages and does not deal with folder structure or northstar packages.** + +**[Related RFC around other package structure issues during convergence](https://github.com/microsoft/fluentui/pull/16577)** + +Contributors: @paulgildea, @JustSlone, @ecraig12345, @khmakoto + +## Summary + +Currently, we have a lot of different component packages, and their purpose, production-readiness, and convergence status are not clear to consumers or contributors. + +There are a few aspects to the proposed solution, involving a mix of code moves and documentation updates: + +- "Converged" component packages should only contain convergence work + - _(done)_ ~~For `react-{checkbox,link,slider,tabs,toggle}`:~~ + - ~~Move old (v8) component implementations back to `react-internal`~~ + - ~~Move prototype "converged" versions to the package roots and get rid of `/next` folders~~ + - Get rid of `react-internal` + - `react-internal` components move back to `react` + - To break a cycle: `react-date-time` components move into `react`, and `react-date-time` re-exports them + - Open question: should we make code location or naming changes to any other `react-*` packages which still contain legacy components? +- Add badges to package readmes to clarify GA/preview/dev status + +## Problem statement + +Currently, we have a lot of different component packages, and their purpose, production-readiness, and convergence status are not clear to consumers or contributors. + +### Background: current packages + +(See also https://github.com/microsoft/fluentui/wiki/Repo-structure) + + +| Package | Notes about current implementation | +|---------|-------| +| `@fluentui/react` | Exports official finished components which we plan to support long-term (or provide good migration paths for major changes). Will be fixed after this proposal: ~~Mostly re-exports other packages, but a few components live here to avoid circular deps.~~ | +| ~~`@fluentui/react-internal`~~ | Going away after this proposal. ~~Split out solely to work around circular dep issues, and most of the code for old components lives here. Nobody should reference it directly outside our repo. `@fluentui/react` re-exports everything from here, and some of the `@fluentui/react-` packages depend on this package.~~ | +| `@fluentui/react-button` | Was previously considered ready for release (and therefore ready to export from `@fluentui/react`), but we've decided that while it's ready for partners to try out and should be stable within this major release, there will be some significant changes in the next major release. | +| `@fluentui/react-cards` | Weird case since there's an old version (built on `@uifabric/foundation` `createComponent` patterns) but it never officially graduated from experimental status and isn't exported from the suite. It also has a `next` folder where the converged version is currently being worked on. | +| `@fluentui/react-date-time` | Previously `@uifabric/date-time`. It's a rewrite (mostly by OWA folks, started awhile ago) of the original OUFR Calendar and DatePicker, but still using older patterns. New for v8, the Calendar and DatePicker from this package are exported from `@fluentui/react` by default. | +| `@fluentui/react-focus` | Current version of FocusZone with most of the work needed to converge with v0's FocusZone. Still differs in are some default values and things that are pulled from the theme. | +| `@fluentui/react-checkbox`
`@fluentui/react-link`
`@fluentui/react-slider`
`@fluentui/react-toggle`
`@fluentui/react-tabs` | These previously default-exported the non-converged (v8) versions of the respective components (with prototype converged versions under `src/next`). The v8 components were recently moved backed to the suite and the convergence work was moved to the root. | +| `@fluentui/react-avatar`
`@fluentui/react-flex`
`@fluentui/react-image`
`@fluentui/react-text` | These only contain work on the converged component versions (in varying states of active work and completeness). | +| `@fluentui/react-charting` | Has active work ongoing but is owned by a different team and doesn't really follow any of the newer patterns we're working on. (Once we establish a pattern for "high-value component" repos, we may split this out.) | +| `@fluentui/react-experiments` | Weird legacy package which we don't have a good story for moving forward, and probably don't recommend (certainly don't promote) for use except by authoring teams of the individual components. It's a mix of components in active development or heavy use by partners, old trials of previous patterns we should definitely delete, and things of unknown status or abandoned. [More discussion here.](https://github.com/microsoft/fluentui/issues/16452) | + + +## Detailed Design or Proposal + +### All v8 components live in `@fluentui/react` + +Motivation: improve contribution story, in some ways improve consumption story. + +- Get rid of `react-internal` _(see detailed discussion below)_ + - Move all components back into `react` + - To break a cycle: move `react-date-time` components into `react`, and have `react-date-time` re-export them +- _(done)_ ~~Move v8 Checkbox, Link, Pivot, Slider, Toggle out of component packages and back to `react`~~ +- _(done)_ ~~`react-{checkbox,link,slider,tabs,toggle}`: Move prototype "converged" components in into the package roots and get rid of `/next` folders.~~ + - The component packages can _temporarily_ depend on `react` if needed for shared implementation parts. + - Before release (ideally ASAP), any deps on `react` would need to be removed and handled with slots intead: e.g. if we haven't gotten to converge Label yet, converged Checkbox by default has built-in `