Skip to content

Latest commit

 

History

History
104 lines (75 loc) · 7.81 KB

contributing.md

File metadata and controls

104 lines (75 loc) · 7.81 KB

Contributing

We are glad you are interested to contribute to this project! Please make sure you've seen the README and license for this project before continuing further. If you work for Truss, check out the guide for Trussels as well.

We welcome contributions in the form of comments, issues, or pull requests with code changes. If you see an error, have a question, or want to share feedback open an issue to discuss. This repository is governed by the Contributor Covenant

Table of Contents

Environment Setup

  1. Use the node environment manager of your choice, but make sure you have the required version specified in .node-version. We recommend using nodenv to manage your node versions, but you can also use homebrew. More info can be found here: how to install Node.js

  2. Use yarn to manage JS packages.

    • Install yarn if you do not already have it.
    • Type yarn or yarn install inside the project directory to install dependencies. You will need to do this once after cloning the project, and continuously if the dependencies in package.json change.

  3. Clone this repo and make sure you can run all of the available commands listed below with no errors.

Available Commands

These should all be run from within the project directory.

  • yarn storybook
    • Starts Storybook server and watches for changed files
    • This will most likely be what you use for active development of components
  • yarn test
    • Starts Jest test runner
    • yarn test:watch is also available
    • Use yarn test:coverage to generate a coverage report
  • yarn build
    • Builds files from /src and outputs to /lib using webpack and UMD library target
    • yarn build:watch is also available
  • yarn example:install
    • Installs dependencies for the example app. This must be run prior to viewing/developing the example application (located in /example).
    • Builds the library files from /src into /lib, and also runs yarn install in the /example directory
  • yarn example:start
    • After installing dependencies, use this to start the example app dev server, so you can view the example app and also add to it.

Development

Before You Start

Make sure you understand the Conventional Commits specification. All pull requests opened into main must have a title that follows the conventional commits spec This generates an automated changelog entry and is later used to determine versioning for release. It is required to merge.

Pull Requests

To begin working on an issue, make sure you've assigned yourself to the issue in Github and marked it as "In Progress.". If there isn't an issue yet for what you want to work on, please create one.

Create a new branch off main using the naming convention:

{your initials or username}-{summary}-{issue #}

For example: hw-accordion-component-112, hw-accordion-component-112

When your branch is ready for review, open a PR into main and request reviews from relevant team members. Reviews from codeowners will automatically be requested. Address any failing tests, lint errors, PR feedback, etc. Once the work is approved, it will be merged with squash & merge.

Note: Currently our CI cannot run directly on external PRs (work from outside the Truss organization) and prevents merge. To manage this, we pull these PRs into a separate branch that a CODEOWNER creates, run automation, and merge from there. Your initial PR will be closed with a comment and your work will be merged instead from the related PR.

Guidelines

  • 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 dependency can focus on integration and implementation.
  • Provide thorough documentation (in Storybook and in the example app) 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.

More guidance for preferred React practices can be found in the adding new components documentation.

Linting, Testing, and Automation

Because this project exports a library that will be used by other projects, it is important that updates follow a set of standard practices. When you commit your changes, several hooks will run to check and format staged files. In order to be eligible for merging, all branches must pass the following automation.

  • Prettier, TypeScript compilation, eslint and stylelint are run on staged files as a pre-commit hook/
    • For an optimal developer experience, it's recommended that you configure your editor to run linting & formatting inline.
  • dangerjs is used to enforce several pull request standards, including:
    • Changes to package source code should include changes to tests.
    • New src/components files should include changes to storybook.
    • New src/components files should be exported from the package entrypoint.
    • Package dependency changes should include yarn.lock updates and yarn audit will be run by danger to ensure no high or critical vulnerabilities are found
  • Jest tests are run in CI and must pass before the branch can be merged
  • Happo.io visual regression tests are run CI against Storybook stories. All diffs must be approved before the branch can be merged. Developers with access (maintainers and many codeowners) log in to Happo.io account to approve/reject diffs.
  • PR titles must follow conventional commits specification.
    • We use standard-version. This auto-generates version numbers and changelog based on commits. We squash & merge PR commits, so the title must be correct.
    • The version number is determined based on the commit prefix - [fix] indicates a bug fix, [feat] indicates a minor bump. [!] or [BREAKING CHANGES] indicates a major bump. Other possibilities include build, ci, chore, docs, perf, refactor, revert, style, test. It is strongly recommended you familiarize yourself with conventional commits.
    • The [WIP] prefix can be used to indicate a pull request is still work in progress. In this case, the PR title is not validated and the pull request lint check remains pending.

Having issues? See FAQs.