From 0849a3093365514741387edd66e7e948861babaa Mon Sep 17 00:00:00 2001 From: HANA Date: Wed, 19 Aug 2020 10:14:12 -0500 Subject: [PATCH] docs: Improve documentation for new contributors, trussels (#402) * add and update docs * Add notes about merging external contributions * Add documentation issue template, comment out descriptions * cleanup and code review --- .github/ISSUE_TEMPLATE/bug_report.md | 26 ++--- .github/ISSUE_TEMPLATE/docs_request.md | 20 ++++ .github/ISSUE_TEMPLATE/feature_request.md | 12 +-- .github/pull_request_template.md | 9 -- README.md | 71 ++++--------- docs/adding_new_components.md | 15 +-- docs/contributing.md | 117 ++++++++++------------ docs/faqs.md | 12 +++ docs/for_trussels.md | 35 ++++--- docs/github_release.png | Bin 169598 -> 0 bytes docs/release_PR.png | Bin 144997 -> 117469 bytes docs/releasing.md | 34 +++++++ docs/{scss.md => styles_and_assets.md} | 42 +++++++- 13 files changed, 219 insertions(+), 174 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/docs_request.md create mode 100644 docs/faqs.md delete mode 100644 docs/github_release.png create mode 100644 docs/releasing.md rename docs/{scss.md => styles_and_assets.md} (53%) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 29f35da146..dcefdac580 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,14 +1,14 @@ --- name: Bug report about: Create a report to help us improve -title: "[bug]" +title: "[fix]" labels: "type: bug" assignees: '' --- **Describe the bug** -A clear and concise description of what the bug is. + **To Reproduce** Steps to reproduce the behavior: @@ -18,21 +18,15 @@ Steps to reproduce the behavior: 4. See error **Expected behavior** -A clear and concise description of what you expected to happen. + **Screenshots** -If applicable, add screenshots to help explain your problem. - -**Desktop (please complete the following information):** - - OS: [e.g. iOS] - - Browser [e.g. chrome, safari] - - Version [e.g. 22] - -**Smartphone (please complete the following information):** - - Device: [e.g. iPhone6] - - OS: [e.g. iOS8.1] - - Browser [e.g. stock browser, safari] - - Version [e.g. 22] + **Additional context** -Add any other context about the problem here. + + +**Device and Browser Information (please complete the following information if describing a UI bug):** + diff --git a/.github/ISSUE_TEMPLATE/docs_request.md b/.github/ISSUE_TEMPLATE/docs_request.md new file mode 100644 index 0000000000..f8fd2cc6f2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs_request.md @@ -0,0 +1,20 @@ +--- +name: Documentation request +about: Suggest documentation (or Storybook) improvements +title: "[docs]" +labels: "type: documentation" +assignees: '' + +--- + +**Does this documentation relate to a specific USWDS feature?** + + +**Is your documentation related to a problem or inconsistency? Please describe.** + + +**Describe the documentation you'd like** + + +**Additional context** + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index aeb7c895d0..0ddc377bf8 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -8,16 +8,16 @@ assignees: '' --- **Does your feature request relate to a specific USWDS feature?** -This project prioritizes work needed to gain full parity with the USWDS components and styles. If your feature request relates to a USWDS feature, please link it here and provide some context. If it doesn't, that's okay, but the request may be reprioritized accordingly. + **Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + **Describe the solution you'd like** -A clear and concise description of what you want to happen. + **Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. + -**Additional context** -Add any other context or screenshots about the feature request here. + **Additional context** + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1e101ed8a8..6b84a0d3cc 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,14 +1,5 @@ - - # Summary - - ## Related Issues or PRs diff --git a/README.md b/README.md index f70069665c..060effe2c3 100644 --- a/README.md +++ b/README.md @@ -4,37 +4,34 @@ [![CircleCI](https://img.shields.io/circleci/build/github/trussworks/react-uswds/develop)](https://circleci.com/gh/trussworks/react-uswds) [![npm downloads](https://img.shields.io/npm/dm/@trussworks/react-uswds)](https://www.npmjs.com/package/@trussworks/react-uswds) -React USWDS 2.0 component library +**ReactUSWDS Component Library** -This is a front end component library whose aim is to develop [React](https://reactjs.org/) implementations of the design patterns defined by the [United States Web Design System (USWDS) 2.0](https://designsystem.digital.gov/). The primary goal of this library is to document and provide common UI components that can be included in other projects that adhere to or are based off of the USWDS, removing a significant amount of overhead UI development from such projects. +This is a frontend component library, built in [React](https://reactjs.org/) with [Typescript](https://www.typescriptlang.org/), based on design patterns defined by the [United States Web Design System (USWDS) 2.0](https://designsystem.digital.gov/). Our primary goal is to document and provide common UI components following the USWDS specification. This library removes a significant amount of overhead UI development for projects based on this standard. -A deployed instance of the ReactUSWDS Storybook is located at: https://trussworks.github.io/react-uswds/ +A deployed instance of the ReactUSWDS Storybook is located at: [https://trussworks.github.io/react-uswds/](https://trussworks.github.io/react-uswds/) -## Table of Contents +An example application, built with React-USWDS, can be found in the `/example` folder and run with the appropriate [`yarn:example` commands](./docs/contributing.md#available-commands). -1. [Background](#background) -1. [Install](#install) -1. [Usage](#usage) -1. [Maintainers](#maintainers) -1. [Contributing](#contributing) -1. [License](#license) -1. [Roadmap](#roadmap) +**Table of Contents** -## Background +- [@trussworks/react-uswds](#trussworksreact-uswds) + - [Background](#background) + - [Non-Goals](#non-goals) + - [Install](#install) + - [Usage](#usage) + - [Maintainers](#maintainers) + - [Contributing](#contributing) + - [License](#license) -The primary deliverable is a published npm package that can be included as a dependency in other projects that use USWDS with React. In order for these components to be actually useful, they should follow best practices and baseline standards for accessible, semantic, markup; be well-tested across browsers and devices; and allow for an appropriate level of customization in implementation (such as via React `props`). Therefore we should adhere to these development guidelines as much as possible: +## Background -- Encourage a strict separation of concerns, focusing on UI (rendered HTML and CSS) rather than any application logic. -- Expose the necessary props for composability and extensibility, such as event handlers, custom CSS classes, etc. -- Maintain a high standard of unit test coverage and cross-browser/device support, so that projects including this depedency can focus on integration and implementation. -- Provide thorough documentation (using a web interface such as Storybook) so that users can view the components as they render in the UI, the source code required to use them, and specifications such as how props are used, a11y support, and test coverage. -- Consistent and transparent versioning so that multiple projects can rely on this package, and it can be maintained as React and USWDS release new versions while also providing backwards compatibility. +The primary deliverable is a published npm package that can be included as a dependency in other projects that use USWDS with React. In order for these components to be useful, they should follow best practices for accessible, semantic, markup; be well-tested across browsers and devices; and allow for an appropriate level of customization. We adhere to a set of [development guidelines](./docs/contributing.md#guidelines) as much as possible and use automation to enforce tests, linting, and other standards. -#### Non-Goals +### Non-Goals -This is not meant to be a one-size-fits-all front end solution to every Truss web project. We are starting off with the very opinionated decision to cater towards a project that wants to use (or at least branch off of) USWDS 2.0, and is using React as a front end framework. +This is not meant to be a one-size-fits-all front end solution, We are starting off with the opinionated decision to cater towards projects that use the U.S. Design System 2.0, and encapsulate these specific styles and markup in React components. -In addition to working towards the above outcomes, we are hoping to gain learnings around how to best abstract out UI code from implementation; help demonstrate and standardize front end code practices for other Truss projects; and develop and distribute a shared JS library to other teams. +In the process, we expect to gain learnings around how to best abstract out UI code from implementation; how to better standardize and document front end code practices; and how to develop, maintain, and distribute a shared JS library in alignment with our [company values at Truss](https://truss.works/values). ## Install @@ -64,37 +61,9 @@ Also make sure to include the following in order to import the compiled CSS from @import '~@trussworks/react-uswds/lib/index.css'; ``` -**[More info about using USWDS CSS & SCSS](./docs/scss.md)** - -### Icons - -[USWDS recommends using Font Awesome](https://designsystem.digital.gov/components/icons/), and that project [provides a package for use with React](https://github.com/FortAwesome/react-fontawesome). - -To add this to your project, install react-font-awesome and at least one style of icon: - -``` -yarn add @fortawesome/fontawesome-svg-core \ - @fortawesome/free-solid-svg-icons \ - @fortawesome/react-fontawesome -``` - -You can then add Font Awesome icons to your projects using the `FontAwesome` component: - - -```jsx -import ReactDOM from 'react-dom' -import { Button } from '@trussworks/react-uswds' -import { FontAwesomeIcon } from '@fortawesome/react-fontawesome' -import { faSave } from '@fortawesome/free-solid-svg-icons' - -const button = ; - -ReactDOM.render(button, document.body); -``` +Note: If you aren't already using USWDS as a dependency, you also need to import uswds styles. **[Read more info about using USWDS styles and assets here](./docs/styles_and_assets.md)** -For more information on working with and configuring react-fontawesome, please see [that project's documentation](https://github.com/FortAwesome/react-fontawesome#installation). To find specific icons for your project, [search on the Font Awesome site](https://fontawesome.com/icons). +Having issues? See [FAQs](./docs/faqs.md). ## Maintainers diff --git a/docs/adding_new_components.md b/docs/adding_new_components.md index a5f7d6d6a8..130d106b10 100644 --- a/docs/adding_new_components.md +++ b/docs/adding_new_components.md @@ -4,7 +4,7 @@ Every new `react-uswds` component needs the following: -- [ ] **A Github issue with the requirements clearly listed.** Requirements include a rough sketch of the expected props and any state the component will handle. +- [ ] **A Github issue with the requirements clearly listed.** Requirements include a rough sketch of the expected props and state the component will handle. - [ ] **A component file (`.tsx`) inside a matching folder** - e.g. `component/GovBanner/GovBanner.tsx`. - [ ] **An export from the package entry point** - e.g. `index.ts` must have the line `export { GovBanner } from './components/GovBanner/GovBanner'` - [ ] **Unit tests** (`test.tsx` file) for logic relating to props and events handlers. @@ -12,7 +12,7 @@ Every new `react-uswds` component needs the following: ## Navigating documentation -We can extrapolate the requirements for `react-uswds` components by referencing several sources. Relevant documentation includes: +We extrapolate the requirements for `react-uswds` components by referencing several sources. Relevant documentation includes: - HTML markup and written descriptions of components in the [design system docs](https://designsystem.digital.gov/components/footer/) - Live code demos in the [uswds storybook](https://components.designsystem.digital.gov/) @@ -29,8 +29,9 @@ Pay special attention to: ### Props -- Require props that are fundamental to the element (such as `id` and `name` for a form input), even if they aren't necessarily "required" HTML attributes. Make all other props optional. -- Extend the standard HTML attributes as props for the primary element in the component. For example, a form can have its own props and also extend the `HTMLFormElement` +- Require props that are fundamental to the element (such as `id` and `name` for a form input), even if they aren't necessarily "required" HTML attributes. - Make all other props optional. +- Avoid [conflicting boolean props](https://spicefactory.co/blog/2019/03/26/how-to-avoid-the-boolean-trap-when-designing-react-components/). When props are mutually exclusive you likely need to use an enum prop instead. See ` +) + +ReactDOM.render(button, document.body) +``` + +For more information on working with and configuring react-fontawesome, please see [that project's documentation](https://github.com/FortAwesome/react-fontawesome#installation). To find specific icons for your project, [search on the Font Awesome site](https://fontawesome.com/icons).