All contributions to this project will be released under the CC0 public domain dedication. By submitting a pull request or filing a bug, issue, or feature request, you are agreeing to comply with this waiver of copyright interest. Details can be found in our TERMS and LICENSE.
There are two primary ways to help:
- Using the issue tracker, and
- Changing the codebase.
Using the issue tracker
Use the issue tracker to suggest feature requests, report bugs, and ask questions. This is also a great way to connect with the developers of the project as well as others who are interested in this solution.
Use the issue tracker to find ways to contribute. Find a bug or a feature, mention in the issue that you will take on that effort, then follow the Changing the codebase guidance below.
Changing the codebase
We work off feature branches from the
After you’ve edited a component,
open a Pull Request to merge your feature branch back into
For example, if you wanted to change
cf-buttons and use it in
here’s what you’d do:
git clone email@example.com:cfpb/capital-framework.git, if you haven’t already.
git checkout master && git pullto ensure you’re on the latest changes (this step is not necessary when cloning for the first time).
yarnto install dependencies and set up workspaces
git checkout -b button-fixto create a new branch for your changes.
- Edit file(s) in
/packages/cf-buttons/however you want.
gulp docsto update the documentation.
yarn run cf-linkto link your local CF components.
cd ~/wherever/cfgov-refresh/to navigate to another project where you’d like to test your buttons changes (in this case, cfgov-refresh).
yarn link cf-buttonsto link cf-buttons to cfgov-refresh.
gulp buildin cfgov-refresh to compile your stylesheets.
- Start cfgov-refresh and navigate to a page with buttons to view your cf-buttons changes.
- When you’re pleased with your changes,
cdback to your
capital-frameworkrepo and commit your changes:
git commit -am "Fix button border radius"
git push origin button-fixto push your branch up to GitHub.
- Go to https://github.com/cfpb/capital-framework and open a pull request to merge
If you are not a current contributor to Capital Framework, use forks by first clicking the fork button on top of the repository and cloning your fork in step 1. In the final step, go to https://github.com/cfpb/capital-framework and file a pull request by clicking the link to compare changes across forks.
Documentation is maintained in each component’s folder’s
Changes to documentation are made on the
master branch using the workflow
above and pulled in the
docs directory using the
gulp docs command.
usage.md files are then rendered as separated pages on Capital Framework’s website
(See this example from cf-core).
Testing components locally
Automated tests can be run with the command
Testing in the documentation site
If you’re hacking on a component and want to test it in the documentation site follow the following steps.
- Ensure that you have the Bundler Ruby gem installed
gem install bundler. (more info).
- Check out a working branch.
- Go into the documentation directory with
bundle installif you haven’t before (also run
bundle exec jekyll serve watchand visit http://localhost:4000/.
- Latest 2 releases of all browsers including:
- Internet Explorer
- iOS Safari
- Opera Mini
- Android Browser
- BlackBerry Browser
- Opera Mobile
- Chrome for Android
- Firefox for Android
- Samsung Internet
- Internet Explorer 9
As well as additional Autoprefixer support for:
- Internet Explorer 8
What this means to the end-user is we’ve added a level of backward compatability for modern features as much as possible. This doesn’t necessarily mean feature parity. Where it’s impossible or impractical to implement a modern feature, we fallback to standard practices for that browser. For example, we do not deliver interactive scripting for Internet Explorer 8, but we do ensure that default browser features continue to work so users that can’t or don’t want to upgrade continue to have access to the site and our content.
We have automated tests that use a headless version of Chrome to ensure the majority of the site is working as expected. For manual testing, we realistically test this project locally or in a virtual environment with the following list of browsers:
- Internet Explorer 8, 9, 10, and 11
- iOS Safari
- Chrome for Android
Autoprefixer parses our CSS and adds vendor prefixes to rules where necessary using reported feature support by Can I Use. For more information visit the [Autoprefixer documentation site] (https://autoprefixer.github.io/).
Known feature differences
- Icons: We currently use icon fonts to deliver scalable icons. Browsers that do not support icon fonts unfortunately do not receive backups but we try to always pair icons with text.
Ready to publish changes to npm?
- Ensure you’re on
git pullto confirm you’re up-to-date.
- Export a personal access token called
yarn run changelogand open
CHANGELOG.mdto see a preview of new changelog entries. We use a tool that scans our Pull Requests for specific labels so if you see a PR missing from the changelog, ensure it has been labeled
- If you’re pleased with the changelog preview,
git checkout CHANGELOG.mdto reset it.
yarn run releaseto start the release.
- If all packages are shown as having been published,
git pushto push changes to the remote
Lerna will update the changelog, ask for a new version number, create a git tag, push to GitHub and publish to npm.
Adhere to any linting errors or warnings
gulp lint linting tasks that are set up within the build processes
are there to promote consistency.
When contributing code please publicly track that there are no linting errors
or warnings using the testing checklist in the pull request description.
Follow our CSS naming conventions
We are using a customized BEM format
.block-name .block-name_element-name .block-name__block-modifier .block-name_element-name__element-modifier
Avoid creating elements of modifiers
Appending an element name to a modifier class can result in a confusing class
Avoid this in favor of using a descendant, like this:
Shoot for mobile first declarations
In most cases styles should be declared mobile first,
then enhanced with
min-width media queries.
By doing this we create a base experience that all devices can use
and one that does not require media query support.