Contributing to the HealthCare.gov Styleguide
Before contributing, please read through this document to ensure the process is easy and effective for everyone involved. You should use the GitHub Workflow (either on your computer, or in the browser) to make any changes to the repository. In other words:
- Never commit directly to the master branch unless you're fixing a very obvious typo or mistake that does not warrant any discussion.
- Open a new pull request to propose changes to any file in this repository. Depending on the changes proposed, the pull request should either be against the master or gh-pages branch.
New to GitHub? The GitHub Guides are a great place to start.
Table of contents
- Starting a new discussion
- Submitting a pull request
- Do I submit a pull request against master or gh-pages branch?
Starting a new discussion
To start a new discussion, simply create a new issue and ask away. Think of it like a traditional list serve. Everyone else in the community will receive an email notification that you've posted a question, and will have the opportunity to reply.
Submitting a pull request
If your discussion's a bit more substantive, such as a document you want others to contribute to or be able to more easily access going forward, or if you want to modify a file already in the repository, consider submitting a pull request. It's super easy:
- Create a new, descriptively named branch. For example, if you want to add a file that describes licensing best practices, a great branch name would be
- Make your changes on that new branch
- Create a pull request against the master or gh-pages branch, asking the community to merge that new branch into the project.
Note: Because filenames are used to generate linkable URLs, all filenames should be lowercase, separating words by hyphens where appropriate.
The web-flow approach
- Navigate to https://github.com/CMSgov/HealthCare.gov-Styleguide in your favorite browser and select the fork button in the top-right corner.
- In your fork, select the branch drop down to create a new, descriptively named branch.
- If you want to edit an existing file, simply select the file name, then select the pencil icon (edit) in the top-right corner of the resulting page. If you want to create a new file, select the new file button and name your file
- Make your changes in the online editor. If you're new to Markdown, click any white space on the page (to move your cursor out of the editor), then press the
mkey for a handy cheat sheet.
- Add a short description of your change, and select the green "Commit changes" button.
- In your fork and in your newly created branch, select the "Compare & pull request" button to create a new pull request. Select either the master or gh-pages branch
- Enter a title and description, and hit submit.
- That's it! Your issue has been submitted, others can comments, and the issue will go through the Styleguide governance process.
The command-line approach
Got Git already set up on your computer? Great. Here are the commands needed to submit a pull request:
git clone https://github.com/CMSgov/HealthCare.gov-Styleguide
git checkout -b [a-descriptive-branch-name]
- (make your changes)
git add .
git commit -m '[a short description of your change]'
git push <forked remote> <a-descriptive-branch-name>
- Head over to your forked repository and change to your descriptive branch name.
- Select the "Compare & pull request" button and select either the master or gh-pages branch.
Do I submit a pull request against master or gh-pages branch?
There are two acceptable branches to submit pull requests against.
If your change or suggestion is on the code of http://styleguide.healthcare.gov, then submit pull requests to the gh-pages branch.
If your change or suggestion is on the code that can be downloaded on the assets landing page, then submit pull requests to the master branch. If the change is accepted, we will ensure this update is also available on the http://styleguide.healthcare.gov website as well.