search

microsoft / fast

The adaptive interface system for modern web experiences.
https://www.fast.design
Other
9.26k stars 593 forks source link

[Proposal] Restructuring repo workspaces #2859

Closed chrisdholt closed 4 years ago

chrisdholt commented 4 years ago

Overview

We've received feedback from time to time from new contributors and people in the community that the number of packages listed in the repo is overwhelming and it's hard to know what to make of the breakdown. This proposal serves to determine a new structure for the repo to make it easier to navigate, find resources, and contribute.

Background

A foundational principle of FAST-DNA has always been to be "framework agnostic" when it comes to our packages - specifically as it relates to "components". At the time, given the state of the industry and project requirements we were unable to pursue web components and custom elements directly. With those constraints, packages were factored to separate framework and technology specific implementations (React or JSS as an example) from framework agnostic implementations to promote reuse and limit the need to rewrite entire parts of the architecture.

As we are now building and developing web components which are themselves a web standard, the factored approach is no longer necessary for anything net-new. Additionally, given our focus on web components, it is unlikely that we will be adding support for any new frameworks (vue, Angular, etc).

Non-goals

This is an organizational change only. This is not intended to change anything regarding the management of the repo (lerna/yarn workspaces). This is not intended to change which packages are bootstrapped together, how builds are run, etc.

Examples of other repos

Implementation

Current tree:

root
    -> packages
        // all packages exist here (26 currently)

Proposed structure:

-> packages
    -> react
        -> fast-components-class-name-contracts-base
        -> fast-components-class-name-contracts-msft
        -> fast-components-foundation-react
        -> fast-components-react-base
        -> fast-components-react-msft
        -> fast-jss-manager
        -> fast-jss-manager-react
        -> fast-jss-utilities
        -> fast-layouts-react
        -> fast-react-utilities
        -> fast-tooling-react
    -> tools
        -> fast-animation
        -> fast-colors
        -> fast-eslint-rules
        -> fast-figma-plugin-msft
        -> fast-storybook-design-system-addon
        -> fast-storybook-presets
        -> fast-tooling
        -> fast-tslint-rules (to be deprecated)
        -> fast-web-utilities
    -> web-components
        -> fast-components
        -> fast-element
-> sites
    -> fast-color-explorer
    -> fast-component-explorer
    -> website

Dependencies

This work is dependent upon the finalization of the framework agnostic tooling work @janechu is driving. Once that work has been merged into master, this change can be implemented. Any work done prior to that being merged will create significant conflicts and issues with the current planned releases.

janechu commented 4 years ago

I wonder if it would be more clear to have the folder for react be react-packages so that there is still a clear indication that these are distributed packages.

I'm a little worried that the fast-figma-plugin-msft, fast-storybook-presets, fast-storybook-design-system-addon and fast-tooling look a little out of place because it seems like those could have a further grouping of tooling-packages. That would mean the packages would purely be for web component and web component related utilities.

SethDonohue commented 4 years ago

I wonder if it would be more clear to have the folder for react be react-packages so that there is still a clear indication that these are distributed packages.

I'm a little worried that the fast-figma-plugin-msft, fast-storybook-presets, fast-storybook-design-system-addon and fast-tooling look a little out of place because it seems like those could have a further grouping of tooling-packages. That would mean the packages would purely be for web component and web component related utilities.

I agree with the more clear folder name of react-packages, especially for a first time user it can help just a little bit more.

chrisdholt commented 4 years ago

One of my hopes is that the naming is landed via conversation here, so "react" is simply a placeholder here. I think we can keep the packages convention, but I'm hesitant to create additional fragmentation of packages if we don't have to - I do think it's worth consideration. I see "packages" as distributed packages which are not sites and are not legacy component implementations. I'm open to having additional buckets added as part of this proposal (tooling or utilities), but would want us to land an intuitive convention and story so it can scale. My personal bent right now is to limit the othering to implementations we expect to deprecate at some point in favor of existing packages.

janechu commented 4 years ago

My concern is only with clarity, so either there should be an additional packages folder for things we don't consider "core" component work, or we need a really good README file at the root of each packages folder that can assist in directing contributors to the right location.

Either way works for me.

EisenbergEffect commented 4 years ago

Would it make sense to pull out the figma, storybook, etc. into a "plugins" or "tools" folder? Maybe something like this:

packages
   tools
   react
   web-components
chrisdholt commented 4 years ago

Would it make sense to pull out the figma, storybook, etc. into a "plugins" or "tools" folder? Maybe something like this:

packages
   tools
   react
   web-components

@EisenbergEffect I'm open to this, but my concern is scalability over time. What happens when we add a package that doesn't fit exactly into each of these buckets? Is it a litmus test for if we create a package (perhaps...)? If we can solve for that, this could definitely be a path forward. As it stands I see it as a potential opportunity for further fragmentation.

While not "legacy", I do think that over time our focus will be on the framework agnostic web components and not adding new features to the React-specific bundles. With that in mind, consider the following:

root
     react (legacy - at some point this will fall off)
     packages
     sites (non distributed packages)

At some point, when the React specific work is no longer under active development we are left with:

root
     packages
     sites
awentzel commented 4 years ago

This is great start. A few thoughts come to mind. Where are the packages for the React tree? Is it confusing not having an obvious packages folder for React?

Based on what I look for on GitHub projects, I would suggest something that explicitly shows web components as this is becoming our differentiated value proposition. Also, it might nice be nice to show this without navigating down one level. Although, I'm not liking that two packages folders might then exist.

Something like this is what may be more intuitive:

root 
    -> Packages
         -> React
         -> Web Components

What do people first look for? Framework recognition, Packages, or something else?

Where would docs live and would there be a separate documentation site for React vs Web Components vs everything?

How would we document the differences. Docs is where markdown lives, website is where the marketing site src and dist lives.

nicholasrice commented 4 years ago

Both lerna and yarn support named workspaces, meaning we could put packages that don't fall into those categories into a root:

- root/
    - packages/
        - react/
            - ...
        - tools/
            - ...
        - web-components/
            - ...
        - foobar
eljefe223 commented 4 years ago

I think having a root folder for each technology is helpful as @nicholasrice and @awentzel mentioned above. 

- root/
    - packages/
        - react/
            - ...
        - tools/
            - ...
        - web-components/
            - ...
        - foobar
chrisdholt commented 4 years ago

@nicholasrice @eljefe223 @janechu @awentzel It sounds like the concept is to have buckets based on how packages ladder up. With that in mind, let's land naming (I have no ideas, my bucket was "packages"). What is our "junk drawer" package? At some point certain things won't fall into all the buckets and so given the proposal for a junk drawer, what do we name these things?

As an aside - I think packages should only be distributed packages. Sites should not be listed alongside them IMO.

EisenbergEffect commented 4 years ago

Hard to define a "junk drawer" but if the library is something that is used by both react and web-components, we could have a "core" or "kernel" folder for that.

janechu commented 4 years ago

@chrisdholt I think @nicholasrice suggestion was that they fall under the root.

https://github.com/microsoft/fast-dna/issues/2859#issuecomment-607989742

awentzel commented 4 years ago

Do we have a couple examples? I like what @EisenbergEffect is suggesting. I get worried putting random things in root, can also overwhelm newbies.

EisenbergEffect commented 4 years ago

Latest update looks solid to me. 👍