This document is about how to contribute to the 18f.gsa.gov site. This process looks a bit different depending on whether you’re a member of the public, an 18F employee, or a member of the outreach or site team. Here’s what you can find in this doc:
No matter who you are, if you spot an error, omission, or bug, you're welcome to open an issue in this repo!
We're so glad you're thinking about contributing to an 18F open source project! If you're unsure about anything, just send us an email with your question — or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. We love all friendly contributions.
We want to ensure a welcoming environment for all of our projects. Our staff follow 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 see an error or have feedback, the best way to let us know is to file an issue.
- To contribute a specific change to the site, outside contributors will need to fork this repo.
There is a team actively working on the site. You can find us in Slack in the #18f-site or #beta-18F-site channels (access is limited to 18F employees).
Any 18F team member should be able to make a branch of the site and submit a pull request. Doing so will also generate a preview URL we can use to inspect your changes. Please do not submit a pull request from a fork of the site, because that does not permit us to inspect your changes.
Because new blog posts are published several times a week, we use several branches to manage parallel work in a predictable way:
- Submit blog posts and minor content edits as pull requests to the
masterbranch. - Submit new design work, content changes, and features as pull requests to the
devbranch. This will allow us to test and review batches of changes before deploying them.
The master, staging, and production branches are protected. Only administrators of the repo can push directly to those branches. 18F teammates who don’t think they have the correct permissions should ask in the #18f-site channel.
If you submit your Pull Request (PR) from the Github website, a form will appear and will be populated with a template. If you are submitting via the Github Client app, a template will not appear and you will need to populate it yourself. You can find the text here. If you are not on the 18F site team, feel free to disregard the template and someone from the team will follow up with you.
To fill out the template, please start by attaching any issues your PR addresses. If the PR changes are not associated with an issue, please leave a brief message detailing what was wrong with the site before, and how it should be.
If the nature of the PR is visual, please replace all instances of BRANCH_NAME with the name of the branch that is being merged.
Complete the PR message by detailing all fixes and tagging GitHub users who should review the work, with a note about what they should be reviewing. In general:
- If you are not an admin or member of the 18F site team, tag someone who you would like to review and merge your PR
- If you are an admin for the repo or a member of the 18F site team, you are responsible for merging your own PRs after they have been reviewed and approved by someone else on the team
- If you have been asked to review a PR, leave a clear message indicating your approval, either through the formal PR review feature or by commenting (at the very least, with a note saying
LGTM, or "Looks good to me") - If your PR includes many small, incremental commits, consider squashing them
- Don’t merge until linters pass, unless you have discussed with reviewers and approved exceptions
This site is based on the U.S. Web Design System (WDS). It is developed using Jekyll, a static site generator based on the Ruby programming language.
We default to using semantic HTML5.
We use HoundCI to automate Sass, JavaScript, and Ruby linting.
We use CircleCI to run HTML Code Sniffer.
CSS methodology is inherited from the WDS, which inherits mostly from the 18f front end guide.
- Use 18F modifed BEM naming convention
- Componentized CSS: start with tag rules and only becomes more specific as necessary, using component classes
The 18F-site team will update the WDS library when it publishes a change required by the site; otherwise it will update bi-monthly (see issue #1877)
- All icons should use
<svg>andxlink(looking for link) formats - All blog images should be under 800kb in total, un-minified size
- Images should be under 600Kb after being minified
- All raster images should be minified with a tool such as grunt-imagemin
This site does not use any heavy JavaScript frameworks, and should always work without JavaScript.
- jQuery is included in the WDS
- Ruby gems is used for front end dependency management
To test the site locally for accessibility errors, we use pa11y-ci to periodically test the site for accessibility concerns.
To set up, do the following:
npm installnpm install -g pa11y-cinpm run pa11y-ci local
- The website supports all versions of Internet Explorer still supported by Microsoft, as well as recent versions of Chrome, Safari, and Firefox
- The website should be designed with a mobile-first approach
Each of the following events should load in under a second:
- Time to blog post image
- Time to main image and callout text
- Time until first blog post title shows up on page with all blog posts
For detailed license information, see LICENSE.
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.