Commit 70b177fe authored by Moncef Belyamani's avatar Moncef Belyamani

Create Engineering Best Practices guide.

This is the inital creation of the guide following the instructions in the guides templates. I've added one page so far (work in progress), with most of the content borrowed from thoughtbot's Git Protocol guide.
## 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.
source ''
gem 'jekyll'
gem 'rouge'
gem 'go_script'
group :jekyll_plugins do
gem 'guides_style_18f'
blankslate (
celluloid (0.16.0)
timers (~> 4.0.0)
classifier-reborn (2.0.3)
fast-stemmer (~> 1.0)
coffee-script (2.4.1)
coffee-script-source (
colorator (0.1)
execjs (2.6.0)
fast-stemmer (1.0.2)
ffi (1.9.10)
go_script (0.1.4)
bundler (~> 1.10)
safe_yaml (~> 1.0)
guides_style_18f (0.1.1)
jekyll (~> 2.5)
rouge (~> 1.9)
sass (~> 3.4)
hitimes (1.2.2)
jekyll (2.5.3)
classifier-reborn (~> 2.0)
colorator (~> 0.1)
jekyll-coffeescript (~> 1.0)
jekyll-gist (~> 1.0)
jekyll-paginate (~> 1.0)
jekyll-sass-converter (~> 1.0)
jekyll-watch (~> 1.1)
kramdown (~> 1.3)
liquid (~> 2.6.1)
mercenary (~> 0.3.3)
pygments.rb (~> 0.6.0)
redcarpet (~> 3.1)
safe_yaml (~> 1.0)
toml (~> 0.1.0)
jekyll-coffeescript (1.0.1)
coffee-script (~> 2.2)
jekyll-gist (1.3.3)
jekyll-paginate (1.1.0)
jekyll-sass-converter (1.3.0)
sass (~> 3.2)
jekyll-watch (1.2.1)
listen (~> 2.7)
kramdown (1.8.0)
liquid (2.6.3)
listen (2.10.1)
celluloid (~> 0.16.0)
rb-fsevent (>= 0.9.3)
rb-inotify (>= 0.9)
mercenary (0.3.5)
parslet (1.5.0)
blankslate (~> 2.0)
posix-spawn (0.3.11)
pygments.rb (0.6.3)
posix-spawn (~> 0.3.6)
yajl-ruby (~> 1.2.0)
rb-fsevent (0.9.5)
rb-inotify (0.9.5)
ffi (>= 0.5.0)
redcarpet (3.3.2)
rouge (1.9.1)
safe_yaml (1.0.4)
sass (3.4.17)
timers (4.0.1)
toml (0.1.2)
parslet (~> 1.5.0)
yajl-ruby (1.2.1)
As a work of the United States Government, this project is in the
public domain within the United States.
Additionally, we waive copyright and related rights in the work
worldwide through the CC0 1.0 Universal public domain dedication.
## CC0 1.0 Universal Summary
This is a human-readable summary of the
[Legal Code (read the full text)](
### No Copyright
The person who associated a work with this deed has dedicated the work to
the public domain by waiving all of his or her rights to the work worldwide
under copyright law, including all related and neighboring rights, to the
extent allowed by law.
You can copy, modify, distribute and perform the work, even for commercial
purposes, all without asking permission.
### Other Information
In no way are the patent or trademark rights of any person affected by CC0,
nor are the rights that other persons may have in the work or in how the
work is used, such as publicity or privacy rights.
Unless expressly stated otherwise, the person who associated a work with
this deed makes no warranties about the work, and disclaims liability for
all uses of the work, to the fullest extent permitted by applicable law.
When using or citing the work, you should not imply endorsement by the
author or the affirmer.
## 18F Guides Template
This is a skeleton repo containing the
[Jekyll]( template for
[18F Guides](
### Getting started
#### Installing Ruby
You will need [Ruby]( ( > version 2.1.5 ). To check
whether it's already installed on a UNIX-like system, open up a terminal
window (e.g. Terminal on OS X) and type `ruby -v` at the command prompt. For
example, you should see something similar to the following:
$ ruby -v
ruby 2.2.3p173 (2015-08-18 revision 51636) [x86_64-darwin14]
If the version number is less than 2.1.5, or instead you see something like:
$ ruby -v
-bash: ruby: command not found
Then Ruby is not installed, and you should choose one of the installation
methods below. [The "Installing Ruby" page of the official
Ruby language web
site]( explains how
to do this in a number of ways across many different systems.
##### Quickest Ruby install/upgrade for OS X
On OS X, you can use [Homebrew]( to install Ruby in
`/usr/local/bin`, which may require you to update your `$PATH` environment
$ brew update
$ brew install ruby
##### Optional: using a version manager
Whether or not Ruby is already installed, we strongly recommend 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.
#### Cloning and serving the Guides Template locally
To create a new guide and serve it locally, where `MY-NEW-GUIDE` is the name
of your new repository:
$ git clone MY-NEW-GUIDE
$ ./go serve
The `./go` script 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
#### Follow the template instructions
The Guides Template (either [running locally](http://localhost:4000) or the
[published version]( will walk you
through the rest of the steps to edit and publish your guide.
### Staging version (for 18F team members)
In addition to the `18f-pages` branch, you can create an `18f-pages-staging`
branch and changes to that branch will be published to
``, which is identical to
`` but provides authenticated access.
### Public domain
This project is in the worldwide [public domain]( As stated in [CONTRIBUTING](
> 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.
markdown: redcarpet
name: 18F Engineering Best Practices
- Gemfile
- Gemfile.lock
- go
permalink: pretty
highlighter: rouge
style: :compressed
# Author/Organization info to be displayed in the templates
name: 18F
# Point the logo URL at a file in your repo or hosted elsewhere by your organization
logourl: /assets/img/18f-logo.png
logoalt: 18F logo
# Navigation
# List links that should appear in the site sidebar here
- text: Collaborating on Code
url: code-collaboration/
internal: true
- name: Guides Template
description: Main repository
url: ""
text: Read more 18F Guides
google_analytics_ua: UA-48605964-19
path: ""
layout: "guides_style_18f_default"
@import "guides_style_18f";
#! /usr/bin/env ruby
require 'English'
Dir.chdir File.dirname(__FILE__)
def try_command_and_restart(command)
exit $CHILD_STATUS.exitstatus unless system command
exec({ 'RUBYOPT' => nil }, RbConfig.ruby, *[$PROGRAM_NAME].concat(ARGV))
require 'bundler/setup' if File.exist? 'Gemfile'
rescue LoadError
try_command_and_restart 'gem install bundler'
rescue SystemExit
try_command_and_restart 'bundle install'
require 'go_script'
rescue LoadError
try_command_and_restart 'gem install go_script' unless File.exist? 'Gemfile'
abort "Please add \"gem 'go_script'\" to your Gemfile"
require 'guides_style_18f'
extend GoScript
check_ruby_version '2.1.5'
command_group :dev, 'Development commands'
def_command :update_nav, 'Update the \'navigation:\' data in _config.yml' do
GuidesStyle18F.update_navigation_configuration Dir.pwd
def_command :update_theme, 'Update the guides_style_18f gem' do
exec({ 'RUBYOPT' => nil }, 'bundle', *%w(update --source guides_style_18f))
def_command :update_gems, 'Update Ruby gems' do |gems|
update_gems gems
def_command :serve, 'Serve the site at localhost:4000' do
def_command :build, 'Build the site' do
execute_command ARGV
permalink: /
title: Introduction
Use this template to create [18F Guides](
and other 18F-branded documentation available on [18F
Pages]( It's structured like an 18F Guides guide,
and it walks you through the process of creating and publishing an 18F Pages document based on
the same theme.
The template is derived from [CFPB/DOCter](
It uses [Jekyll]( as the rendering engine.
## Create a new guide/document
To get started on a new guide (or other document based on this theme),
follow [the "Getting started" instructions in the 18F/guides-template GitHub
repository]( to create
a local clone of this template.
Once you've created a clone, click the _Add a New Page_ entry in the table of
contents to begin the rest of the steps.
## Update an existing guide/document
__Note: You only need to do this if your existing guide or document is not already
using the `guides_style_18f` gem or if it does not have an `18f-pages`
Add the [`guides_style_18f` gem]( to your
guide's `Gemfile`, if it's not already present. You may also wish to copy the
`./go` script from the template if your document doesn't already have one.
To receive layout updates, as well as any new styles or scripts associated
with them, you will need to run `./go update_theme`. Or — if you aren't using
a `./go` script — you can run `bundle update --source guides_style_18f`
If your repository already has a `gh-pages` branch, you can create an
`18f-pages` branch from it by running these commands:
$ git checkout -b 18f-pages gh-pages
$ git push origin 18f-pages
Follow the instructions in _Update the Config File_ to update your
`_config.yml` accordingly. You may also need to consult the _GitHub Setup_ and
_Post Your Guide_ chapters to ensure your guide is correctly published to
`` and linked from the main [18F
Guides]( site.
permalink: /code-collaboration/
title: Collaborating on Code
Initial content borrowed from:
Collaborating on Code
A guide for programming within version control.
Maintain a Repo on GitHub
* Make all new repos public by default unless there's a compelling reason not
* Avoid including files in source control that are specific to your
development machine or process.
* Delete local and remote feature branches after merging.
* Perform work in a feature branch.
* Rebase frequently to incorporate upstream changes.
* Use a [pull request] for code reviews.
[pull request]:
Write a Feature
Create a local feature branch based off master or your main development branch.
git checkout master
git pull
git checkout -b <branch-name>
Rebase frequently to incorporate upstream changes.
git fetch origin
git rebase origin/master
Resolve conflicts. When feature is complete and tests pass, stage the changes.
git add --all
When you've staged the changes, commit them.
git status
git commit --verbose
Write a [good commit message]. Example format:
Present-tense summary under 50 characters
* More information about commit (under 72 characters).
* More information about commit (under 72 characters).
If you've created more than one commit, use a rebase to squash them into
cohesive commits with good messages:
git rebase -i origin/master
Share your branch.
git push origin <branch-name>
Submit a [GitHub pull request].
Ask for a code review in the project's chat room and add a "ready to review"
label on the PR in GitHub to make it easy to see all PRs that are ready
to be reviewed.
[good commit message]:
[GitHub pull request]:
Review Code
A team member other than the author reviews the pull request. They follow
Code Review guidelines (forthcoming) to avoid
They make comments and ask questions directly on lines of code in the GitHub
web interface or in the project's chat room.
If comments need to be addressed, the pull request author makes changes and
lets the reviewer know it's ready to be reviewed again.
Repeat until all comments have been addressed. The reviewer then merges the PR
and deletes the branch.
Rebase interactively. Squash commits like "Fix whitespace" into one or a
small number of valuable commit(s). Edit commit messages to reveal intent. Run
git fetch origin
git rebase -i origin/master
Force push your branch. This allows GitHub to automatically close your pull
request and mark it as merged when your commit(s) are pushed to master. It also
makes it possible to [find the pull request] that brought in your changes.
git push --force origin <branch-name>
View a list of new commits. View changed files. Merge branch into master.
git log origin/master..<branch-name>
git diff --stat origin/master
git checkout master
git merge <branch-name> --ff-only
git push
Delete your remote feature branch.
git push origin --delete <branch-name>
Delete your local feature branch.
git branch --delete <branch-name>
[find the pull request]:
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment