We’re so glad you’re thinking about contributing to a Technology Transformation Services (TTS) 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.
TTS is committed to building a safe, welcoming, harassment-free culture for everyone. We expect everyone on the TTS team and everyone within TTS spaces, including contributors to our projects, to follow the TTS Code of Conduct.
We encourage you to read this project’s CONTRIBUTING policy (you are here), its LICENSE, README and its Workflow process.
If you have any questions or want to read more, check out the 18F Open Source Policy GitHub repository, or send us an email.
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.
To help us get a better understanding of the issue you’re submitting, follow our ISSUE TEMPLATE and the guidelines it describes.
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
develop
that 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
develop
branch.
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: StorybookJS and Gulp. Once you've cloned this
repository, you'll need to install its dependencies:
npm install
ProTip: You can also use Yarn, which tends to install dependencies more quickly than npm.
To start the StorybookJS server, run:
npm start
Then, visit http://localhost:6006/ 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.
If you're working on the JavaScript or CSS, you can run the "watch" task in another shell to automatically rebuild the distribution files that StorybookJS references with:
npm run watch
To run the component unit tests, run:
npm test
This will also run eslint and stylelint to ensure that the JavaScript
and SCSS source files meet our coding standards along with [snyk test] to check for package dependency vulnerabilities. To lint without the unit
tests, you'll need Gulp. Install it globally (npm install -g gulp-cli
), then run:
npm run lint // JS linting
gulp lintSass
(Or, if you don't want to install Gulp globally, you can run npx gulp
instead of gulp
.)
If you want to run a single test file, run npm run mocha ${path/to/spec-file}
,
substituting the actual path to the spec. Only javascript files can be executed by the mocha
runner,
and only those js files in the packages/
directory ending with a .spec.js
.
Alternatively, you can add an .only
to a describe
or it
block (i.e. describe.only('my spec')
)
and run the npm run test
command. Keep in mind that this will also run linters and aXe accessibility tests.
To run all of the unit tests, run npm run test:unit
.
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.
This project follows the 18F Front End Guide CSS and JavaScript. Please use this guide for your reference.
See browser support in the “Developer Documentation”.
See the release documentation for more information on our git/GitHub release workflow.
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 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.
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.