search

microsoft / fluentui

Fluent UI web represents a collection of utilities, React components, and web components for building web applications.
https://react.fluentui.dev
Other
18.36k stars 2.72k forks source link

RFC: Fluent UI React converged component process - WIP #16203

Closed JustSlone closed 3 years ago

JustSlone commented 3 years ago

Contributors: @khmakoto, @behowell, @joschemd, @aneeshack4, @dzearing, @paulgildea

Summary

This RFC covers a proposal for a process to track and bring clarity to the engineering work required to build a Fluent UI Next component

Prior art

This proposal is based on the existing component specs here: https://github.com/microsoft/fluentui/tree/master/specs

Problem statement

We have had difficulty talking about the status of our converged components. If they are done, inprogress, what is done, whether they are ready to use or not, etc. The reality is that convergence is not just a single step, it's a long effort with multiple checkpoints along the way that all may be in varying states of progress. Therefore simply tracking a single component's status is not sufficent.

We also need to, as a team, both focus on and scale out the component convergence effort. If things go well, we will have many components in flight at the same time. For this to work, we will need a way to know what is in progess, and what will be needed to keep the progress moving.

TODOs

Proposal

To solve the above problem, we propose a few things

  1. The phases of convergence
  2. A component spec template and review process
  3. A GitHub issue template to track detailed component status
  4. An update to the existing component spreadsheet to track high level status

1. The Phases of convergence

The purpose of the phases of convergence is to give us both a common langauge to discuss both what needs to be done to "converge" a component, as well as to understand how far along we are.

2. Spec review process and Template [TODO]

The goals of the spec review process are to enable asynchronous reviews, authors of components not within our immediate team, and unblocking incremental progress on implementing the component.

Preqs:

Steps:

  1. Spec should be added as API.md file in component package folder
  2. Spec review takes place async in PR
    • PR is for adding API.md and other files to the package folder
  3. Schedule an initial meeting to review spec
    • Initial spec review meeting should focus on progress through spec and track contenious issues in PR for follow up later
  4. Follow up offline on open issues from initial review
    • It's fine to schedule follow up discussions or meetings as needed

Proposed Sections of Spec

Based on: https://github.com/microsoft/fluentui/tree/master/specs

Recomendation: Write a component.types.ts file instead of documenting props in markdown table

3. GitHub Issue template

Below is the propose GitHub Issue template. We would have 1 per component. This is the source of truth for status on component convergence.

From: #15759

Preparation:

  • [ ] Open UI Research complete
  • [ ] Comparison on v7 and v0 complete
    • [link to issue]
  • [ ] Gather open GitHub issues related to component in epic issue
    • [link to issue]
  • [ ] react-* package scaffolded
    • [link to package]
  • [ ] Component Spec authored and reviewed
    • [link to spec in component package]
  • [ ] Deliverable: Reviewed component spec

Implementation

[link to react-* package folder]

  • [ ] Implement component
  • [ ] Add storybook stories
  • [ ] Add tests - Conformance, Unit, and VR
  • [ ] Write README.md covering basic usage
  • [ ] Write initial MIGRATION.md guide (include v7 and v0)
  • [ ] Deliverable: Experimental component ready for partner use

Validation

  • [ ] Add and validate in UI Builder
  • [ ] Add and validate in docs site
  • [ ] Validate with token pipeline
  • [ ] Validate in product
  • [ ] Finalize migration guide
    • [ ] Author codemods
  • [ ] Deliverable: Preview component ready for broader/3rd party use

4. Tracking sheet

image

Pros and Cons

:+1: Gives structure and clarity to convergence :+1: Allows us to provide status and rough ETAs to partners :-1: Has the risk to just add more overhead tracking things

Discarded Solutions

This is the first try at a solution. We did iterate on some small choices around where we put the spec.

Open Issues

msft-fluent-ui-bot commented 3 years ago

Because this issue has not had activity for over 150 days, we're automatically closing it for house-keeping purposes.

Still require assistance? Please, create a new issue with up-to date details.