From 8a31879f4d0975baca3c8cb744cdfd90dd41bede Mon Sep 17 00:00:00 2001 From: Brian Douglas Date: Tue, 16 May 2023 05:57:23 -0700 Subject: [PATCH] feat: removes outdated open-sauced docs (#86) * removes outdated open-sauced docs * removes config --------- Co-authored-by: Brian 'bdougie' Douglas --- docs/technical/dark-mode-explained.md | 76 --------------------- docs/technical/fetching-data-from-github.md | 68 ------------------ docusaurus.config.js | 4 -- sidebars.js | 2 - 4 files changed, 150 deletions(-) delete mode 100644 docs/technical/dark-mode-explained.md delete mode 100644 docs/technical/fetching-data-from-github.md diff --git a/docs/technical/dark-mode-explained.md b/docs/technical/dark-mode-explained.md deleted file mode 100644 index d61855ac..00000000 --- a/docs/technical/dark-mode-explained.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -id: dark-mode-explained -title: Dark mode explained -sidebar_label: Dark mode explained -keywords: - - dark mode explained ---- - -# Dark mode explained - -This project supports "dark mode" styling, and by default it will follow the color preference on your device. It also allows for overriding this using buttons at the top right of the screen, which will persist the preference to local storage on your device. More info about color preference web API's can be found here in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme). - -## Implementation approach - -The implementation is done in 4 steps. - -- The functional component in `src/containers/App.js` has a `useEffect` hook that checks the user's `localStorage` for a stored entry of `theme`. This value should be either "dark", "light", no entry at all. The hook runs only on initial page load, and if no local storage entry is found, it uses a default value of "system". It applies this value to the `ThemeContext` defined in `src/ThemeContext.js`. -- Also found in `src/containers/App.js` is a function called `systemIsDark` that can look at the user's device color preference to determine whether or not the system would prefer dark mode. -- Also found in `src/containers/App.js` is a function called `applyTheme` that checks the theme value and decides whether to include or remove the CSS classname "dark" to the `document.body` element. This determination would be made according to this table. - -| Value of `theme` | Result of `systemIsDark` | Apply `body.dark`? | -| ---------------- | ------------------------ | ------------------ | -| system | true | include | -| system | false | remove | -| dark | N/A | include | -| light | N/A | remove | - -- Found in `src/components/ThemeButtonGroup.js` is a component with three buttons, each of which can be used to change the `ThemeContext` value. - -## Theme context use - -At this time, the `ThemeContext` only affects the `ThemeButtonGroup` component from a logic standpoint, but the `body.dark` CSS class declaration affects many places in the codebase. The broad effects of the `body.dark` CSS class declaration are found in `src/index.css`. -There are more specific impacts for components that extend `styled-components` (found in `src/styles/`) and the style declarations for these refer to descendants of `body.dark`. These impacts are found in overrides of color-related properties such as `color`, `background-color`, `fill`, and `filter`. - -## SVG images - -SVG images can have their coloring controlled by a few different means, depending on the way they're rendered. This project has some mix in its use of SVG files for icons/images. - -- In the case of its use of the library `@primer/octicons-react`, these SVG files are rendered directly into markup rather than as the `src` attribute of an `` tag, and so the `fill` CSS property is controlled by `src/index.css`. -- In the case of its use of SVG files in the repository, these are rendered as the `src` attribute of an `` tag, and therefore the `filter` CSS property is controlled by `src/index.css`. -- In the case of an SVG used as a background-image for a form element (`src/styles/Search.js`), we use an alternate SVG file for dark mode whose `fill` property has been adjusted, since this use case doesn't allow for controlling the SVG colors separately from the form element's background colors. - -## Loading skeletons - -This project uses components from the library `react-loading-skeleton`, and these are addressed in `src/index.css` based on [this file](https://github.com/dvtng/react-loading-skeleton/blob/master/src/skeleton.js) from their source code. - -## Best practices moving forward - -For future work, components with coloring aspects should make use of the `styled-components` library and should include CSS style declarations to handle the case of `body.dark`. For example, below is a component definition used in `src/styles/TextArea.js`: - -```js -import styled from "styled-components"; -import { margin, size, borderRadius, colors, fontSize } from "./variables"; -const Container = styled.textarea` - margin-bottom: 12px; - border-radius: ${borderRadius}; - border: 1px solid ${colors.lightestGrey}; - box-sizing: border-box; - box-shadow: none; - font-size: ${fontSize.default}; - margin-bottom: ${size.tiny}; - outline: none; - padding: ${size.tiny}; - width: 100%; - body.dark & { - background-color: ${colors.darkestGrey}; - color: ${colors.lightestGrey}; - } -`; -``` - -## References - -- [Dark Mode at Stack Overflow](https://stackoverflow.blog/2020/03/31/building-dark-mode-on-stack-overflow/) -- [Color Control of SVGs](https://medium.com/@union_io/swapping-fill-color-on-image-tag-svgs-using-css-filters-fa4818bf7ec6) -- [React Context Docs](https://reactjs.org/docs/context.html#consuming-multiple-contexts) diff --git a/docs/technical/fetching-data-from-github.md b/docs/technical/fetching-data-from-github.md deleted file mode 100644 index cb706e25..00000000 --- a/docs/technical/fetching-data-from-github.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -id: fetching-data-from-github -title: Fetching data from the GitHub graphql API -sidebar_label: Fetching data from the GitHub graphql API -keywords: - - Fetching data from the GitHub graphql API ---- - -Over the past few years, GitHub has been enabling developers to build on our platform as 3rd party integrators. This enablement does not come without limitations such as rate-limiting and token access. Open Sauced originally started as a way to try out the GitHub GraphQL API with a production-ready application. - -## Implementation approach - -Open Sauced is exclusively powered by the public data from open source repos. Not only is the data drawn from open sourced repos, the onboarding flow for Open Sauced walks the user through creating their own open sourced repo in order to track their own contributions. - -## OneGraph - -[OneGraph](https://www.onegraph.com/) is the tool used to consume the GitHub GraphQL API through one consistent GraphQL interface. - -## Persisted queries - -Persisted queries are an advanced GraphQL feature that allow clients to pre-register queries with the server. In a typical workflow, the client will send the query to the server as part of a build process and the server will send back an id for the query. When the client wants to run the query, it sends the id instead of the full query string. - -Developers use persisted queries because they reduce the amount of bandwidth sent from the client to the server and they improve security by locking down the queries that can be sent to the server. - -OneGraph makes this all easy to do, and you can read up more on that in [their documentation](https://www.onegraph.com/docs/persisted_queries.html). - -## Goals repository - -Each Open Sauced user leverages their own GitHub repository as a database. The repository is generated during sign up and is the companion for finding open source contributions to make. All data in this repository is a mirror of the data you see on the opensauced.pizza dashboard. - -The repo [open-sauced/goals-template](https://github.com/open-sauced/goals-template) is used as a template repo to generate the user's `open-sauced-goals` repo. - -**data.json** -The Open Sauced goal data in this list is populatated using the [goals-caching.yml](https://github.com/open-sauced/actions/blob/main/goals-caching/update-open-sauced-goals-cache.js). Each opened issue in the goals repo full name is stored along with star, forks, and issues count. This is needed for rendering the user's open sauced dashboard. - -**stars.json** -The Open Sauced recommendation data is stored using the logged in user's starred repositories. This data is accessible via the GitHub API and stored publically in goals repo for easy rendering. The list is populatated using the [goals-caching.yml](https://github.com/open-sauced/actions/blob/main/goals-caching/update-open-sauced-goals-cache.js). _Plans are being developed to power platform wide recommendations using this data, this is pending the reviewing of the GitHub TOCs_. - -## Use of API in components - -The following table shows which components (`src/components/*.js`) use which API functions (`src/lib/apiGraphQL.js', 'src/lib/persistedGraphQL.js`), and what they do. - -| Component | API Function | Persisted/Dynamic | Mutation | -| ------------------- | -------------------------------------------------------------------------------------------------------- | ----------------- | -------- | -| AddRepoForm | `api.createGoal`
Add goal through form input | Dynamic | x | -| Contributions | `api.persistedInteractionsFetch`
Contributions list for the user | Persisted | | -| CreateGoals | `api.fetchOwnerId`
Need the repo owner ID first | Dynamic | | -| CreateGoals | `api.createOpenSaucedGoalsRepo`
Create from template | Dynamic | x | -| DangerZone | `api.updateGoal`
Remove the goal | Dynamic | x | -| Issues | `api.persistedIssuesByLabelFetch`
Fetch Goal's issues labeled `good first issue` (First 5) | Persisted | | -| Issues | `api.persistedIssuesFetch`
Fetch Goal's all issues (First 5) | Persisted | | -| Issues | `api.persistedRepositoryIssuesByLabelFetch`
Fetch Goal's all issues (Paginated) | Persisted | | -| Issues | `api.persistedRepositoryIssuesFetch`
Fetch Goal's issues labeled `good first issue` (Paginated) | Persisted | | -| NoteForm | `api.updateGoal`
Updates Notes | Dynamic | x | -| RecommendedRepoList | `api.createGoal`
Add goal based on recommendations list | Dynamic | x | -| Repository | `api.persistedRepoDataFetch`
Gather partial data for goal | Persisted | | -| Repository | `api.fetchGoalQuery`
Gather partial data for goal | Dynamic | | -| Repository | `api.persistedForkFetch`
Look at whether user has this repo forked | Persisted | | -| Repository | `api.persistedForkFetch`
Initiate forking the repo for the user | Persisted | | -| RepositoryGoals | `api.persistedViewerStars`
Fetch repos starred by the user | Persisted | | -| AdminStatsBar | `api.fetchRateLimit`
Shows administrator the status of rate limiting | Dynamic | | -| AdminStatsBar | `api.persistedDeploymentFetch`
Shows administrator deployment status | Persisted | | -| AdminStatsBar | `api.fetchRepoCount`
Shows administrator the user count, based on count of `open-sauced-goals` repos | Dynamic | | - -## References - -- [Using Persisted Queries](https://www.onegraph.com/docs/persisted_queries.html) -- [GraphQL Enterprise Connect: "Persisted GraphQL", Brian Douglas](https://www.youtube.com/watch?v=yr5kSZljBxo) diff --git a/docusaurus.config.js b/docusaurus.config.js index 4bedaa0a..5cf58699 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -83,10 +83,6 @@ module.exports = { label: 'Contributing guide', to: '/contributing/introduction-to-contributing/', }, - { - label: 'Technical guide', - to: '/technical/dark-mode-explained/', - }, { label: 'Maintainer guide', to: '/maintainers/setting-up-a-new-repository/', diff --git a/sidebars.js b/sidebars.js index 3531cf85..68333baf 100644 --- a/sidebars.js +++ b/sidebars.js @@ -29,8 +29,6 @@ module.exports = { collapsed: false, items: [ 'technical/introduction-to-storybook', - 'technical/dark-mode-explained', - 'technical/fetching-data-from-github', 'technical/resolve-merge-conflicts', ], },