Umbrella: F8 2017 App Improvements

[caabernathy]

Below is an outline of several master issues to help improve the F8 2017 app. These could serve as mentorship projects where smaller, dependency issues are created to coordinate work.

When an issue is created that captures the proposed work, this master issue can be edited to include a link to that issue.

Color Themeability

Problem:

We'd like to make it easy to change colors, across the entire app and within specific screens.

Currently:

There are classes that try to centralize theming (e.g. F8Colors, F8Button), but they aren't flexible enough to handle the needs of individual screens. They also aren't consistent with how the themes are referenced -- theme name, color name, direct values passed into helper functions? For expediency, many files simply hardcode the right values and ignore the helper classes altogether.

Ideally:

It should be obvious how to complete a task like, "change all the headers to be purple". We should minimize premature abstractions that might make it harder to quickly verify that the task is completed correctly. Consistency is key.

Proposal:

• Make it easy to find and update all color references (e.g. change all usages to something easily searchable, like F8Theme.getColor("blue"))
• Identify common color usage patterns, both app-wide and screen-specific
• Design a solution to address the color usage patterns to make necessary changes easy
• Migrate the uniform color call-sites to use the new solution
• Create a lint rule to ensure all color usages follow the latest convention

Font Themeability

Problem:

We'd like to make it easy to change fonts, across the entire app and within specific screens.

Currently:

There are classes that try to centralize theming (e.g. F8Fonts, F8Button), but they aren't flexible enough to handle the needs of individual screens. They also aren't consistent with how the themes are referenced -- theme name, color name, direct values passed into helper functions? For expediency, many files simply hardcode the right values and ignore the helper classes altogether.

Ideally:

It should be obvious how to complete a task like, "change all the headers to use Helvetica". We should minimize premature abstractions that might make it harder to quickly verify that the task is completed correctly. Consistency is key.

Proposal:

• Make it easy to find and update all font references (e.g. change all usages to something easily searchable, like F8Theme.getFont("Helvetica", "Bold"))
• Identify common font usage patterns, both app-wide and screen-specific
• Design a solution to address the font usage patterns to make necessary changes easy
• Migrate the uniform font call-sites to use the new solution
• Create a lint rule to ensure all font usages follow the latest convention
• Create a script to install font files in the right directory and configure the native clients to package them

Icon Themeability

Problem:

We'd like to make it easy to change icons, across the entire app and within specific screens.

Currently:

There are scattered call-sites and inconsistent directory structures for storing and referencing image assets.

Ideally:

It should be obvious how to complete a task like, "change the Share icon to use this image". A developer should be able to guess where an icon is stored and how to replace it. Consistency is key.

Proposal:

• Make it easy to find and update all image references (e.g. change all usages to something easily searchable, like F8Theme.getImage("share.png"))
• Identify common image usage patterns, both app-wide and screen-specific
• Design a solution to address the image usage patterns to make necessary changes easy
• Migrate the uniform image call-sites to use the new solution
• Create a lint rule to ensure all image usages follow the latest convention
• Create a script to pre-process and install in-app image files in the right directory
• Create a script to pre-process and install app icons in the native client for the OS to display

Component Reusability

Problem:

We'd like to make it easy to change up layouts and navigation, across the entire app and within specific screens.

Currently:

The directory structure is difficult to navigate, and there are several components that seem to be generic but are only used in a single call-site and are difficult to repurpose for new views.

Ideally:

It should be obvious how to complete a task like, "change the navigation to use a side drawer instead of tabs at the bottom". A developer should be able to see a component on the screen and guess where its source file is stored. They should also be able to change a component and be fairly confident about which screens are impacted and how.

Proposal:

• Map out the component hierarchy of the app and all the screens
• Identify the fundamental reusable components that are necessary for three or more components
• Refactor the directory structure to better match the app's component hierarchy
• Refactor the components to use the reusable components
• Inline or move potentially-reusable components with fewer than three call-sites to one of the call-sites
• Reorganize helper functions and app-wide classes into a library directory

Dead Code Cleanup

Problem:

We'd like it to be easy to understand the impact of changing each line of code.

Currently:

There's a fair amount of commented code, unreachable conditions and verbosity from supporting unnecessary use cases.

Ideally:

Every line of code should be obviously useful and necessary.

Proposal:

• Browse around and delete unnecessary lines or simplify conditions
• Create a lint rule to detect dead code

Flow Cleanup

Problem:

We'd like it to be easy to verify that code won't crash at runtime.

Currently:

The Flow definitions are missing, only partially complete or inconsistent.

Ideally:

The vast majority of non-test files should have complete definitions, especially ones that are commonly reused. The valid types of inputs to each function should be obvious. Flow should be able to provide quick and useful feedback when there's a type error.

Proposal:

• Identify common object structures and export type definitions from a reasonable call-site
• Migrate un-typed files to import and reuse type definitions

Dependency Updates

Problem:
We'd like to use the latest version of libraries and follow the latest conventions.

Currently:

A lot of dependencies are out-of-date, and we're still using a lot of ancient patterns (e.g. React.createClass)

Ideally:

The libraries should be up-to-date and all consistently use modern conventions.

Proposal:

• Go through the package.json and check the latest version for each library
• Update each library, find errors and fix them
• Create a script to figure out dependencies to update