Skip to content

Latest commit

 

History

History
142 lines (93 loc) · 8.16 KB

CONTRIBUTING.md

File metadata and controls

142 lines (93 loc) · 8.16 KB
Raw

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 the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. We appreciate all friendly contributions.

We want to ensure a welcoming environment for all of 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, and its README.

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

Submitting an issue

To help us get a better understanding of the issue you are submitting, please leverage the following outline (as used in the following Girl Develop It issue template):

Description

Include a high-level description of the feature or error here including steps of how to recreate it if applicable. Include any benefits, challenges, or considerations. This can be short and sweet.

Ask

Describe the desired behavior and what would deem this issue, bug, or feature complete.

To Do

  • Steps
  • To
  • Complete/Fix

Additional Info

Include any images, steps to recreate, notes, emojis, or whatever.

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 that lightly defines what you're working on (e.g. 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, push your branch up to the repo.
  6. Submit your pull request against the 18f-pages-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. This 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

The task above is similar to the previous ./go serve command from earlier versions of the Standards. 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.