We’re so glad you’re thinking about contributing to an 18F open source project! If you’re unsure about anything, just ask — or submit your issue or pull request anyway. The worst that can happen is we’ll politely ask you to change something. We appreciate all friendly contributions.
One of our goals is to ensure a welcoming environment for all contributors to our projects. Our staff follows the 18F Code of Conduct, and all contributors should do the same.
Contributor Guidelines for Design
We have provided some guidelines for folks that would like to submit new components to the U.S. Web Design System and the lifecycle those new components will go through. For more detail, please visit the guidelines on our wiki.
Submitting an issue
To help us get a better understanding of the issue you’re submitting, follow our ISSUE TEMPLATE and the guidelines it describes.
Submitting a pull request
Here are a few guidelines to follow when submitting a pull request:
- Create a GitHub account or sign in to your existing account.
- Fork this repo into your GitHub account (or just clone it if you’re an 18F team member). Read more about forking a repo here on GitHub: https://help.github.com/articles/fork-a-repo/
- Create a branch from
developthat lightly defines what you’re working on (for example, add-styles).
- Ensure that your contribution works via
npm, if applicable.
- Once you’re ready to submit a pull request, fill out the PULL REQUEST template provided.
- Submit your pull request against the
Open an issue if you have questions or need help with setup.
The U.S. Web Design System
uswds package (the zip download and the
files needed to use the Design System on your project) is built primarily with
two Node.js tools: Fractal and Gulp. Once you’ve cloned this
repository, you’ll need to install its dependencies:
ProTip: You can also use Yarn, which tends to install dependencies more quickly than npm.
To start the Fractal live reload server, run:
Then, visit localhost:3000 in a web browser to peruse the component library. While the server is running, any changes that you make to the component templates or configurations will reload the page automatically.
npm run watch
To run the component unit tests, run:
and SCSS source files meet our coding standards. To lint without the unit
tests, you’ll need Gulp. Install it globally (
npm install -g
gulp-cli), then run:
gulp eslint gulp stylelint
(Or, if you don’t want to install Gulp globally, you can run
bin)/gulp instead of
Note that running the tests also requires an installation of Chrome v59 or higher (v60 if you’re on Windows).
Visual regression testing
The Design System comes with optional tooling for detecting visual regressions, which can be especially useful if you’re refactoring CSS.
These tests work by comparing current screenshots of the Design System’s Fractal components to “golden” screenshots that represent what the components are supposed to look like.
Golden screenshots are stored on your local development system only;
they’re not version controlled. This means that after making changes to a branch,
you can switch to the branch you’d like to compare it to (e.g. the
branch) to generate your golden screenshots.
To generate the golden screenshots, run:
node spec/visual-regression-tester.js test --updateGolden
Then, make any CSS refactorings (or switch to a branch that has them).
To compare the current state of your CSS to the golden screenshots, run:
node spec/visual-regression-tester.js test
If the current screenshots don’t match their golden counterparts, you will be directed to an HTML file that visually shows the differences between any conflicting screenshots.
To build the
uswds package in preparation for releases, run:
npm run release
The purpose of our coding styleguides are to create consistent coding practices across 18F. The styleguide should be treated as a guide — rules can be modified according to project needs.
- Each pull request creates a new coverage report on Code Climate.
- Code Climate then posts a status message back to GitHub that lists the coverage percentage on that branch, and the difference between that number and the one last reported on our default branch.
High code coverage numbers are generally good, and we would prefer that our coverage increases over time. We will not categorically reject contributions that reduce code coverage, but we may ask contributors to refactor their code, add new unit tests, or modify existing tests to avoid significant reductions in coverage.
See browser support in the “Getting started: Developers” guidelines.
Our use of branches
See the release documentation for more information on our git/GitHub release workflow.
Licenses and attribution
A few parts of this project are not in the public domain
For complete attribution and licensing information for parts of the project that are not in the public domain, see the LICENSE.
The rest of this project is in the public domain
The rest of this project is in the worldwide public domain.
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
Contributions will be released into the public domain
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.