Whether building a site, a feature enhancement or fixing a bug, all code sits in a Github repository. Developers can access the project and create a development versions on their local system. We also recreate the live site on our remote development server which our clients can view. Once a client approves any changes on the development site, we push that change to the live site. This process ensures we are developing in a responsible, secure and redundant/versioned manner.

Pre-Code Checklist

Before you even write a line of code, there's some research and prep work that needs to be done in order to avoid stalls close to launch. * If any, research the client's existing web services (domain registrar, DNS, hosting, mail, etc.). Don't assume that their current hosting package comes with all that you'll need to run the new site. Some folks don't support PHP! * Sign up for accounts/services you'll be using for the site (Google Analytics, Vimeo, Youtube, Mailchimp, etc.). Trying to round up all the login info on short notice can get tricky!

More info coming soon!


Typical setup

System setup:

  1. Make sure you have Node.js installed. If you are unsure go to Terminal and run node -v. If installed you should get a version # such as v0.10.35 npm is installed as part of node.

  2. If not installed, install node.js globally by running sudo npm install npm -g

  3. If you need to upgrade node.js, you upgrade using npm by running:

sudo npm cache clean -f
sudo npm install -g n
sudo n stable
  1. Make sure you have Bower installed by running bower -v. If nothing appears, install Bower globally by running npm install -g bower
  1. Next, make sure you have Gulp installed by running gulp -v. If nothing appears, install globally by running npm install --global gulp

Project setup:

  1. Navigate to your site root or themes directory
  2. Install Bower packages by running bower install
  3. Install Gulp by running npm install gulp. You may have to run sudo npm install gulp depending on how your system is setup
  4. Load all devDependencies from package.json by running sudo npm install
  5. Run gulp to create dist folder and files and some other neat stuff
  6. Run gulp watch to watch

Git workflow

The key to establishing a great team workflow with Git is communication. Deciding the workflow "rules of the road" ahead of time will help eliminate friction and confusion, and allow a team to take advantage of what Git does best: boost productivity.


All development/fixes/enhancements are worked on from a developers forked version of the repo. Once work is completed a "pull request" is issued. All pull requests should merge into the develop branch. Some good pull request principles are: * Commit often * Commit small

Once your work has been merged into develop branch, you will need to update your local develop branch from the project remote repo. You will essentially have two remotes. Pulling from projects remote and pushing to your forked remote once work is completed.

Master Branch

The master branch is always deployable. Always.

A deployable master branch is important for many reasons: * It enables anyone new to a project to pull and build immediately without errors. * master shows the current state of production and/or the shipped product. * A deployable master is a safety net. If master is always deployable, then we can deploy without worry.

Develop branch

The develop branch should be the main branch for ongoing development.

Feature branches are created and merged back into develop, and develop represents the bleeding edge of our codebase. Since both master and develop are permanent and highly-trafficked branches, they should never be worked in directly. Instead, all work should be done in feature branches. When implementing a new feature, branch from develop and hack out the feature.

Branch naming, Commit messages and Pull requests


Once your new feature is coded, it's time to get it back into a shared branch (let's assume we're merging into develop). But before merging into develop, make sure that your feature branch has the latest changes from develop because there may be conflicts.

All conflict resolution should happen in your feature branch. If you branched to make a small change/fix and you have not pushed the branch to the remote, rebase develop into your feature branch, and then merge your feature branch into develop. Push and then feel free to delete your local feature branch.

If you have pushed your branch to the remote, first merge develop into your branch (resolving conflicts), and then merge your branch into develop. Push and feel free to delete both the local and remote feature branch.

When rebasing, keep in mind that it is a destructive action. Meaning... be careful! Rebasing is really useful for cleaning up commit histories, but you don't want to rewrite history on anything that has been shared with someone else.

Here are a couple of rules to keep you safe when rebasing:

git checkout my-feature
git rebase develop
git checkout develop
git merge my‑awesome-feature

Peer review

Code reviews are a good thing! They allow you to get valuable feedback on the work you’ve done, and—if nothing else—increase the probability of mistakes being caught and fixed.

This is where Git’s pull requests come in handy. Pull requests can be much more than just reviewing changed code. Since pull requests are brand-based, they can become threads for discussing and collaborating on individual features.

Ready to ship

Once develop is ready for a release, we merge into master


We should try and never ship mistakes...but when we do, it's best to fix them fast. Since develop may include unfinished features, hotfixes should be branched from the current release—which is master (because master is always deployable!).

To make a hotfix, branch off master, make the fix, then do a non-fast-forward merge into master. Tag it, then merge master back into develop (because we'll want develop to have the fix too).

Project File Structure


Try to use HTML5 tags as much as possible. It makes your code much more semantic when you compose it with descriptive tags; creating a sidebar with the <aside> tag instead of <div class="sidebar"> makes the code more understandable.

All CSS and HTML will incorporate BEM Syntax, as it helps when a developer jumps into another developer's existing code.

The basic syntax is as followed: .block {}; .block__element {}; .block--modifier {};


These are the main block elements. They're often the main chunks that build the entire webpage.


Elements are descendents of .block, and help to form .block as a whole. They are usually the children of the main block.


As the name hints - these are 'modifications' of an element. Modifiers represent a different state or version of .block, .block__element, etc., and usually refer to a change in the appearance of a block/element.


/* Block component */ .btn {}

/* Element that depends upon the block */ .btn__price {}

/* Modifier that changes the style of the block */ .btn--orange {} .btn--big {}

<div class="form-button">
    <p class="form-button__text">Hello</p>

<div class="form-button form-button--red">
    <p class="form-button__text">Hello</p>

The second button will inherit all the styles from .form-button, but adding the class of .form-button--red modifies its appearance. In this case, from the name of the MODIFIER, we understand that this button will be red (though it may incorporate other styling as well). We want to be as concise and descriptive as possible with our naming scheme.

.form-button {
    width: 200px;
    height: 50px;
    background-color: rgba(0, 0, 0, 1);
    border-radius: 3px;

    // this will output as '.form-button__text'
    // in terms of BEM Syntax, this is an ELEMENT of '.form-button'
    > @at-root #{&}__text {
        font-weight: 700;

// this will output as '.form-button--red'
// in terms of BEM Syntax, this is a MODIFIER of '.form-button'
.form-button--red {
    background: rgba(255, 0, 0, 1);

Every single element does not need to use BEM. Even if an element is nested within another, you can start a new BEM sequence just related to that particular child element.

Just a little example:

<article class="overview">
    <section class="overview__intro">
        <p class="overview__intro--firstpara">This first paragraph will be style differently from the rest.</p>
        <p>Insert regular paragraph text here.</p>
        <p>Insert regular paragraph text here.</p>
    <div class="mini-banner mini-banner--green">
        <p class="mini-banner__text">Hello! It's nice to meet you!</p>

You can read the following articles to learn more: * MindBEMding – getting your head ’round BEM syntax * CSS-Tricks - BEM 101

SCSS File Structure

Break Into As Many Small Files As Makes Sense -There is no penalty to splitting into many small files. Do it as much as feels good to the project. I know I find it easier to jump to small specific files and navigate through them than fewer/larger ones.

When planning your CSS architecture, folders are essential: you don’t just drop every Sass file into the same folder, you categorize them.

Here’s how we recommend organizing your files:

|– base/ 
|   |– _reset.scss       # Reset/normalize 
|   |– _typography.scss  # Typography rules 
|   ...                  # Etc… 
|– components/ 
|   |– _buttons.scss     # Buttons 
|   |– _carousel.scss    # Carousel 
|   |– _cover.scss       # Cover 
|   |– _dropdown.scss    # Dropdown 
|   |– _navigation.scss  # Navigation 
|   ...                  # Etc… 
|– helpers/ 
|   |– _variables.scss   # Sass Variables 
|   |– _functions.scss   # Sass Functions 
|   |– _mixins.scss      # Sass Mixins 
|   |– _helpers.scss     # Class & placeholders helpers 
|   ...                  # Etc… 
|– layout/ 
|   |– _grid.scss        # Grid system 
|   |– _header.scss      # Header 
|   |– _footer.scss      # Footer 
|   |– _sidebar.scss     # Sidebar 
|   |– _forms.scss       # Forms 
|   ...                  # Etc… 
|– states/ 
|   |– _home.scss        # Home specific styles 
|   |– _contact.scss     # Contact specific styles 
|   ...                  # Etc… 
|– themes/ 
|   |– _theme.scss       # Default theme 
|   |– _admin.scss       # Admin theme 
|   ...                  # Etc… 
|– vendors/ 
|   |– _bootstrap.scss   # Bootstrap 
|   |– _jquery-ui.scss   # jQuery UI 
|   ...                  # Etc… 
`– style.scss             # primary Sass file 

As you can see, there is only one Sass file at the root level: style.scss. All the other files are divided into appropriate folders and prefixed with an underscore (_) to tell Sass they are partial .scss files that shouldn’t be compiled to .css files. Indeed, it is the style.scss file’s role to import and merge all of those.


The base/ folder holds what we might call the boilerplate stuff for your project. In there, you might find some stuff dealing with typography, and, depending on the project, maybe some other files.


The helpers/ folder (sometimes called utils/) gathers all Sass tools and helpers we’ll use across the project. Got a function? A mixin? Put it in there. This folder also contains a _variables.scss file (sometimes _config.scss) which holds all global variables for the project (for typography, color schemes, and so on).


The layout/ directory (sometimes called partials/) usually contains a number of files, each of them setting some styles for the main sections of the layout (header, footer, and so on). It also contains the _grid file which is the grid system used to build the layout.


For smaller components, there is the components/ folder (frequently called modules/). While layout/ is kind of macro (defining the global wireframe), components/ is more micro. It can contain all kinds of specific modules like a slider, a loader, a widget, or anything along those lines. There are usually a lot of files in components/ since your site should be mostly composed of tiny modules.


If you have page-specific styles, you can put them in a pages/ folder and in a file named after the page. For example, it’s not uncommon to have very specific styles for the home page, so you’d have a _home.scss file in pages/ dealing with this.


If you are working on a large site with multiple themes, having a themes/ folder can make sense. You can stuff all your theme/design related styles in there. This is definitely project-specific.


And last but not least, you will probably have a vendors/ folder containing all the CSS files from external libraries and frameworks – Bootstrap, jQueryUI, and so on.



// first we set descriptive variables:
$darkgrey: #333333;
$blue: #001eff;

// then we set functional variables:
$text_color: $darkgrey;
$link_color: $lightblue;
$border_color: $lightblue;

.myClass {
    color: $text_color;
    border-color: $border_color;
a {
    color: $link_color;


.sidebar-button {
    @extends %button;
    background: $light-blue;
    @include transition( all 0.3s ease );
    > a {
        border: 1px solid $border_color;
        @include transform(rotate( 90deg ));
    // this will output as '.sidebar-button__text'
    // in terms of BEM Syntax, this is an ELEMENT of '.sidebar-button'
    > @at-root #{&}__text {
        font-weight: 700;
    // this will output as '.sidebar-button--blue'
    // in terms of BEM Syntax, this is a MODIFIER of '.sidebar-button'
    > @at-root #{&}--blue {
        background: rgba(0, 0, 255, 1);


Here is a good example:

// in terms of BEM Syntax, this is a MODIFIER of '.sidebar'
.sidebar--blue {

    width: 700px;
    height: 200px;
    background: rgba(0, 0, 255, 1);
    border: 1px solid rgb(0, 255, 0);
    color: rgb(0, 0, 0);


JavaScript & Filestructure


Directory Structure

Since we're using a modular and component-based architecture, the directory structure below will do:

|   |– index.js
|– components/ 
|   | slideshow/
|   |   |– slideshow.js   # Sass Variables 
|   ...                  # Etc… 
|– modules/
|   | hero/
|   |   |– hero.js   # Sass Variables 
|   ...                  # Etc…  
|– states/ 
|   |- home.js
|   |- archive.js
|   ...
|– helpers/ 
|   |- helpers.js



let $masthead__intro-fullwidth = $('.masthead .intro.fullwidth');

Working with Stable Versions

We want to be working with the latest stable version of Wordpress at all times.

From the terminal follow these steps: * Make sure you're in the 'wordpress' folder of your project (you'll see that you're on the 'master' branch * git branch -a * git tag (to see all subversions) * git fetch --tags (this fetches/grabs all the updates since you initially cloned the wordpress git repo) * git checkout tags/(whatever the newest stable version is) * git checkout -b stable (create a 'stable' branch)

And now you're working with the latest stable version! Repeat this all when a new version comes out!



Custom Post Types


As a general rule, we try and use as few plugins as necessary. Preferring to code functionality as necessary over using plugins. If plugins need to be used they need to be vetted by team first.