Skip to content

Latest commit

 

History

History
127 lines (84 loc) · 8.09 KB

CONTRIBUTING.md

File metadata and controls

127 lines (84 loc) · 8.09 KB

Welcome!

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 contibutors to our projects. Our staff follows the 18F Code of Conduct, and all contributors should do the same.

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 just shoot us an email.

Guidelines

Contributor Guidelines for Design

We have provided some guidelines for folks that would like to submit new components to the Draft Web Design Standards 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:

  1. Create a GitHub account or sign in to your existing account.
  2. 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/
  3. Create a branch from staging that lightly defines what you're working on (for example, add-styles).
  4. Ensure that your contribution works via npm, if applicable. See below under Install the package locally via npm-link.
  5. Once you're ready to submit a pull request, fill out the PULL REQUEST template provided.
  6. Submit your pull request against the staging branch.

Have questions or need help with setup? Open an issue here https://github.com/18F/web-design-standards/issues.

Building the project locally with gulp

The Draft U.S. Web Design Standards uswds package (the ZIP download and the files needed to use the Standards on your project) and Standards website (our public site that displays examples of each component and the HTML code) are built using gulp automation. To use gulp, first make sure you've installed it on your machine globally.

npm install --global gulp-cli

Then, to start, run the following command to install any new dependencies:

npm install

The following examples detail a few tasks you'll encounter as you use gulp:

gulp build

The task above is an alias for running gulp sass javascript images fonts and is the task to build all assets. Building the package will generate a /dist directory with the contents of the ZIP archive made available to download. Building just the package is useful if you'd like to create your own distribution bundle for frameworks that aren't supported via npm. The files in /dist contain no documentation and are compiled and bundled CSS, JavaScript, fonts, and images files. The command is aliased by npm run prepublish.

gulp website:build

The task above builds the entire Draft U.S. Web Design Standards website locally. It can be useful when debugging for build errors or generating a deployable version of the Standards website. This creates a /_site directory that contains the Jekyll-built site. This is the same build step that we use to deploy the website. The command is aliased by npm run deploy.

gulp website:serve

After running this command, you’ll be able to view the Draft U.S. Web Design Standards website locally (http://127.0.0.1:4000). This also sets up gulp and Jekyll to watch for file changes to the /docs and /src directories and rebuilds the website accordingly. The command is aliased by npm start

Licenses and attribution

A few parts of this project are not in the public domain

The Source Sans Pro font files in assets/fonts are a customized subset of Source Sans Pro, licensed under the SIL Open Font License, and copyright Adobe Systems Incorporated, with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries.

The Merriweather font files in assets/fonts are from Google Web Fonts, licensed under the SIL Open Font License, and copyright Sorkin Type Co with Reserved Font Name 'Merriweather'.

The files in assets/img are from Font Awesome by Dave Gandy under the SIL Open Font License 1.1.

The files in assets/_scss/lib/bourbon are from Bourbon, copyright thoughtbot, inc., under the MIT license.

The files in assets/_scss/lib/neat are from Neat, copyright thoughtbot, inc., also under the MIT license.

The file assets/css/normalize.min.css is from Normalize.css, copyright Nicolas Gallagher and Jonathan Neal, under the MIT license.

The file assets/js/component.js includes politespace.js from Politespace, copyright Zach Leatherman, under the MIT license.

The file assets/js/vendor/html5shiv.js is from HTML5 Shiv, copyright Alexander Farkas (aFarkas), under the MIT license.

The file assets/js/vendor/jquery-1.11.3.min.js is from jQuery, copyright The jQuery Foundation, under the MIT license.

The file assets/js/vendor/rem.min.js is from REM unit polyfill, copyright Chuck Carpenter, under the MIT license.

The file assets/js/vendor/respond.js is from Respond.js, copyright Scott Jehl, under the MIT license.

The file assets/js/vendor/selectivizr-min.js is from Selectivizr, copyright Keith Clark, under the MIT license.

The files assets-styleguide/js/vendor/prism.js and assets-styleguide/css/prism.css are from Prism, copyright Lea Verou, under the MIT 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.

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.