Skip to content
This repository has been archived by the owner. It is now read-only.
Browse files
  • Loading branch information
Melody Kramer committed Jul 27, 2015
1 parent 734ab03 commit dca309331e5cb7175a98774d4a25bd332a896332
Showing with 34 additions and 51 deletions.
  1. +19 −0
  2. +15 −51
@@ -0,0 +1,19 @@
## 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 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 have any questions or want to read more, check out the [18F Open Source Policy GitHub repository](, or just [shoot us an email](

## 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.
@@ -1,65 +1,25 @@
## 18F Guides Template
## 18F Open Source Style Guide

This is a skeleton repo containing the
[Jekyll]( template for
[18F Guides](

### Generating the site/hosting locally
This guide helps people document code repositories so that they're easy to use and understand. In each section, we outline our strategies for making sure that our code repositories are clear, accessible, and user-friendly.

You will need [Ruby]( ( > version 2.1.5 ). You may
consider using a Ruby version manager such as
[rbenv]( or [rvm]( to
help ensure that Ruby version upgrades don't mean all your
[gems]( will need to be rebuilt.
It’s important to make sure our documentation is clear both for internal and external audiences. As our team expands, we want our new employees to easily find and use our existing codebases.

On OS X, you can use [Homebrew]( to install Ruby in
`/usr/local/bin`, which may require you to update your `$PATH` environment
It's also really important if we want to make outside contributors feel welcome or have outside organizations fork and use our code. ([And we do!]( Explaining what a project is, why it's important, and how people can help ensures that people can fork and adapt our projects.

$ brew update
$ brew install ruby
This guide also contains a checklist we created that helps ensure our repos are clear, accessible, and user-friendly. Some terminology used may be GitHub-specific, but the concepts are applicable regardless of your version control system or platform. We wrote it so that both non-coders and coders can understand it. (If something is not clear, please let us know.)

To create a new guide and serve it locally, where `MY-NEW-GUIDE` is the name
of your new repository:
We’re sharing it because it we think it’s helpful for lots of organizations, including our own. We know that many of our repos don’t conform to this exact style. By articulating a specific style, we hope this document will also help us improve our own practices.

$ git clone MY-NEW-GUIDE
$ ./go init
$ ./go serve

This will check that your Ruby version is supported, install the [Bundler
gem]( if it is not yet installed, install all the gems
needed by the template, and launch a running instance on
`http://localhost:4000/guides-template/`. (Make sure to include the trailing slash! The built-in
Jekyll webserver doesn't redirect to it.) That page contains further
instructions on how to adapt the template to a new guide repository.
## How to use this guide

After going through these steps, run `./go` to see a list of available
commands. The `serve` command is the most common for routine development.
We created this guide for reference on an as-needed basis. It’s here when you’re wondering how to describe a repo, for instance, or when you’re wondering how to create a friendly, informational tone when writing issues for users.

You'll need to create a new Github repository for your new guide. To do this, go to and click the "New Repository" button. Enter the title and description for your new guide and then click "Create Repository".
To this end, we’ve structured the guide into descriptively named sections. Browse our table of contents to find the topic you’re looking for.

After the repository is created, you'll see the repo URL at the top. Copy this url by hitting the handy "Copy to Clipboard" button next to the text box.
Most importantly, we encourage you to make a copy of this document and adapt it to your organizational needs. This guide is just that: a guide. It’s not meant to provide the final opinion on any of the topics discussed. If a certain section isn’t relevant to you and your team, delete it. And if you feel the guide is missing a section, by all means, add it by clicking 'edit this page' at the bottom of every page. This guide is yours to use, and we trust you’ll update it in the ways that best suit you.

Go back to the directory where you cloned the guides-template repository. We're going to change this repo to point to the one you just created (which is empty) and push the template to it.
git remote set-url origin
git push origin 18f-pages

Now you can edit the template freely, and push up changes as you need.

### Staging version

You can create an `18f-pages-staging` branch and changes to that branch will
be published to ``.

TODO(mbland): Finish

### Public domain

@@ -70,4 +30,8 @@ This project is in the worldwide [public domain]( As stated in [CONT
> 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.
# open-source-guide

### Contact us

If you'd like to contact us, please create a GitHub issue or email

0 comments on commit dca3093

Please sign in to comment.