docs: add documentation for Trussels (#190)

* docs: add documentation for Trussels

* docs: clean up readme to meet project standards

* docs: add to active maintainers

* docs: add first pass of security policy

Co-authored-by: HANA <hana@truss.works>

README.md

@@ -1,22 +1,27 @@
 # @trussworks/react-uswds
 
-[![CircleCI](https://circleci.com/gh/trussworks/react-uswds.svg?style=svg&circle-token=a003f78b224f32fcab60155e3c0917a8040c5b96)](https://circleci.com/gh/trussworks/react-uswds)
-
+[![npm version](https://img.shields.io/npm/v/@trussworks/react-uswds)](https://www.npmjs.com/package/@trussworks/react-uswds)
+[![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)
 [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
 
-## Summary
+React USWDS 2.0 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.
 
-Interested in contributing? See our [guidelines and dev setup here](./docs/contributing.md).
+A deployed instance of the ReactUSWDS Storybook is located at: https://trussworks.github.io/react-uswds/
 
 ## Table of Contents
 
-1. [Goals](#goals)
+1. [Background](#background)
+1. [Install](#install)
 1. [Usage](#usage)
+1. [Maintainers](#maintainers)
+1. [Contributing](#contributing)
+1. [License](#license)
 1. [Roadmap](#roadmap)
 
-## Goals
+## Background
 
 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:
 
@@ -26,23 +31,29 @@ The primary deliverable is a published npm package that can be included as a dep
 - 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.
 
-### 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.
 
 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.
 
-## Usage
+## Install
 
 Install this package with npm or yarn:
 
 ```
 yarn add @trussworks/react-uswds
+```
+
+or
 
-npm install @trussworks/react-uswds
 ```
+npm i @trussworks/react-uswds
+```
+
+## Usage
 
-You can then import modules using ES6 syntax:
+You can import modules using ES6 syntax:
 
 ```
 import { Alert } from '@trussworks/react-uswds'
@@ -56,30 +67,29 @@ Also make sure to include the following in order to import the compiled CSS from
 
 **[More info about using USWDS CSS & SCSS](./docs/scss.md)**
 
-## Roadmap
-
-- [x] Add lint configs and pre-commit hooks for contributing
-- [x] Set up CI for running tests and linting
-- [x] Add support for and convert existing component(s) to TypeScript
-- [x] Decide on and document git workflow for this project
-- [x] Decide on and document release workflow for the package
-- [x] Load and export USWDS CSS
-- [x] Load and export USWDS fonts/svgs/other assets
-- [x] Decide on long-term lib publishing/hosting solution
-- [x] Add CI status badge
-- [x] Setup https://danger.systems/js/ to check on contribution standards, possibly even checking yarn install for warnings
-- [ ] Document decision behind node version and upgrade plan
-- [ ] ADR to decide on and set up a React component test helper:
-  - https://airbnb.io/enzyme/
-  - https://testing-library.com/docs/react-testing-library/
-- [ ] Enable `pkg.module` entrypoint for better module and tree shaking:
-  - https://github.com/rollup/rollup/wiki/pkg.module
-  - https://stackoverflow.com/questions/41289200/output-an-es-module-using-webpack
-- [ ] Add more documentation around how to contribute and write new components
-- [ ] Add component scaffolding shortcut (for generating component, tests, stories files with template code)
-- [ ] Add testing coverage collection
-- [ ] Set up Storybook as public Github page
-- [ ] Add example application that uses the library to the repo
-- [ ] Add visual testing automation tool (i.e., Loki)
-- [ ] Enforce adding to CHANGELOG when merging a PR into develop
-- [ ] Make sure new components are added as package exports
+## Maintainers
+
+- [@suzubara](https://github.com/suzubara)
+- [@haworku](https://github.com/haworku)
+
+## Contributing
+
+Interested in contributing? See our [guidelines and dev setup here](./docs/contributing.md).
+
+Are you a Trussel and new to this project? Check out our [on & offboarding guide](./docs/for_trussels.md) made just for you!
+
+## License
+
+[Copyright 2019, TrussWorks, Inc.](../LICENSE)
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

docs/for_trussels.md

@@ -0,0 +1,71 @@
+# For Trussels
+
+Below is documentation specifically to provide guidance for contributors who work at [Truss](https://github.com/trussworks). If you don't work at Truss, please feel free to ignore!
+
+### Internal Communication
+
+We have a Truss Slack channel dedicated to discussing this project (**#react-uswds**), as well as a channel for automated updates such as new issues, pull requests, and releases (**#react-uswds-feed**). Anyone is welcome to join and participate in these channels, whether or not they are an active maintainer.
+
+We also have a regularly scheduled check-in meeting, which serves as a catch-all stand-up / backlog grooming / sprint planning for anyone who is actively working on the library. This meeting is also open to anyone, but is focused on discussing current & upcoming work, and any blockers or questions that need to be resolved. The meeting cadence and attendance will vary depending on who is an active maintainer, and the agenda and notes can be found via the #react-uswds channel.
+
+## Active Maintainers
+
+Anyone may feel free to contribute to this library, regardless of what other projects they may be staffed on. For example, if you are on a client project that happens to use this library, it makes sense that you might want to add new features or make bug fixes as you encounter them in a real-life implementation.
+
+However, in some cases you may find yourself spending a more significant amount of time to help maintain ReactUSWDS, such as if you are on Reserve. In that case, it's helpful to have a designation of **_active maintainer_**, which will indicate certain additional responsibilities and a higher level of involvement than other contributors.
+
+Regardless of whether you are on client work or Reserve, it is _up to each individual_ to delineate themselves as an active maintainer, and perform the following on- or off-boarding tasks as needed.
+
+### Active maintainer responsibilities include:
+
+- Maintain a presence in the #react-uswds channel, especially to answer any implementation questions from Trussels who are _not_ active maintainers
+- Attend and help facilitate the ReactUSDS check-in meetings regularly
+- Pay attention to [USWDS](https://github.com/uswds/uswds) updates, and create new issues needed to help this project stay up-to-date with them
+- Participate actively in PR reviews, issue discussion, and project roadmap planning
+- Keep an eye on any security alerts that come up, and make sure they are addressed promptly (see below)
+- Assist with shepherding library releases forward, and publishing to npm
+- Prevent PRs and issues from becoming stale, and clean up the ones that do
+- Moderate this repo and help keep it aligned with Truss project values
+
+### Addressing Security Alerts
+
+Typically any security alerts we receive will be related to third-party dependencies. This repo is currently configured so that Dependabot will automatically open PRs that fix dependency vulnurabilities, so ideally most of the time manual intervention is not needed. There may also be periods of time during which an alert is issued, but the related dependencies have not yet updated -- in this case, we usually choose to accept the risk of waiting until the updates have been released. However, if an exceptional case comes up -- such as a high severity vulnurability or even a vulnurability within this library -- and you aren't sure how to handle it, you can ask for help in one of the following Truss Slack channels (in order of relevance): #react-uswds, #g-frontend, #infrasec, #engineering
+
+## Onboarding
+
+First of all, we’re so excited you want to be an active maintainer on this project! Here are the things you should make sure to do:
+
+- [ ] Join the #react-uswds Slack channel
+- [ ] Add yourself to the ReactUSWDS weekly check-in (this can be found on the Truss Events calendar)
+- [ ] If you haven't already, be sure to familiarize yourself with this repo, especially the docs on [contributing](./contributing.md) and [recent releases](https://github.com/trussworks/react-uswds/releases)
+- [ ] Open a new PR that adds yourself to the Active Maintainers list in the [readme](../README.md).
+  - [ ] If you aren't already, you can also add yourself to the `contributors` list in the [package.json](../package.json),
+  - [ ] and to [CODEOWNERS](../CODEOWNERS) if you'd like to automatically be requested to review PRs _(this is optional)_.
+- [ ] _Optional:_ If you want access to the npm org so you can publish new releases, ping `@npm-admins` in Slack
+
+If you've completed all of the above and are wondering what to do next, here are some ideas!
+
+- Check out any [open pull requests](https://github.com/trussworks/react-uswds/pulls) that might need reviews or feedback
+- Take a look at the [project board](https://github.com/trussworks/react-uswds/projects/1) to get a sense of current and upcoming work
+  - Issues in the **Ready for development** column should have clear scope and acceptance criteria, and are ready to be worked on!
+    - especially any that are labeled `good first issue` if this is your first time contributing to ReactUSWDS
+  - Issues in the **Needs requirements** column are undergoing active discussion and would probably benefit from your point of view!
+- Browse [open issues](https://github.com/trussworks/react-uswds/issues) to see if there are any new issues that need to be labeled or prioritized
+- Check in with any other active maintainers about what areas are in need of help
+
+## Offboarding
+
+We’re equally excited that you’ll be taking something off your plate and moving on to something new! Please make sure to do the following before you wash your hands of responsibilities:
+
+- **If you have any in-progress work that you won't be able to complete:**
+  - [ ] Make sure all of your commits have been pushed up to a branch so nothing gets lost on your local machine
+  - [ ] Open a draft PR for your branch, and use that to annotate any remaining work, TODOs, open questions, etc. as well as the overarching strategy you had in mind. The more documentation you leave, the easier it will be for someone else to finish your work!
+  - [ ] If there are other active maintainers who are planning to pick up your work, comment on the PR and tag them so it's clear who will be picking it up. If there aren't, or you aren't sure, comment on the PR saying the work needs a new assignee or else it will go stale.
+  - [ ] Unassign yourself from any corresponding issues
+  - It’s ideal if you are able to help answer any questions that arise from handing off work, but we understand if your new commitments don't allow for it! Don't feel pressure to stay available after offboarding.
+- [ ] Open a new PR that removes yourself from the Active Maintainers list in the [readme](../README.md).
+  - You can also remove yourself from [CODEOWNERS](../CODEOWNERS) so you don't get PR requests that you won't have time to review.
+  - **_Don't_** remove yourself from `package.json` contributors! You did good work on this project and that should be recognized.
+- [ ] _Optional:_ You don’t need to have npm access revoked, but you can if you want.
+- [ ] _Optional:_ Give yourself some time back and remove yourself from the weekly check-in events
+- [ ] _Optional: If you want to,_ feel free to leave the #react-uswds Slack channels