Creating a New Project

Step 1: Creating a new repo Step 1: Creating a new repo

The first step to starting a new project is to set up the repository on GitHub. This repository will be the home for the codebase, and will be used for deployments for projects we host. For most projects, it’ll also be the home of the issue tracking for the project.

Create a new repository on GitHub under the humanmade organisation.

Note: For projects on VIP, you’ll also need a deployment repository. This will be created for you by the VIP team.

Step 2: Set up project structure Step 2: Set up project structure

Once you have the repo, you need to set up the initial codebase. Generally, you should follow the standard project structure.

The recommended way to do this is via hm-cli, which sets up a repo based on hm-base for you automatically. If you’d prefer to do it manually, see the instructions below.

Note that VIP projects must always be set up manually.

Via hm-cli Via hm-cli

The easiest way to set up the project codebase is to use hm-cli.

If you don’t already have it installed, install it via npm:

# Install globally:
npm install -g @humanmade/cli

Then, cd to your projects directory, and run the new project command:

hm project create my-project-directory-name

hm-cli will then ask you a series of questions about the project. These will be used to set up the codebase and generate a readme for the project.

Generating project into /Users/rmccue/Work/Human Made/projects/my-project-directory-name

Project
-------
? Project Name: Foobar
? Client Name: FooCorp
? Private Slack Room: foobar-private

People
------
? Project Manager: Dee Teal
? Lead Engineer: Ryan McCue
? Other Team Members: Joe Hoyle
? Other Team Members: Tom Willmot
? Other Team Members:

Client Team
-----------
? Client Team Members: John Smith
? Client Team Members:

Structure
---------
? Project Type: HM Hosted
? Is there a production environment? Yes
? Production Domain: foobar.xyz
? Production Branch: master
? Is there a staging environment? Yes
? Staging Domain: foobar-staging.aws.hmn.md
? Staging Branch: staging

Other Details
-------------
? Repository Name: foobar

hm-cli will also update WordPress and hm-platform to the latest release. It will automatically set up the git remote to point to your repository too.

✔ Cloned hm-base
✔ Updating WordPress to latest version
✔ Generating README
✔ Committing updates
✔ Success! Created project at /Users/rmccue/Work/Human Made/projects/foobar

Once complete, you can then push your codebase up to the repository:

# Switch to newly created directory
cd foobar

# Push up to GitHub
git push -u origin master

Manually (for HM hosted projects) Manually (for HM hosted projects)

If you’d prefer to do things a little more manually, you can use the hm-base repository to get started.

# Clone this repository:
git clone --recursive git://github.com/humanmade/hm-base.git your-project-name

# Navigate to the new directory.
cd your-project-name

# Update hm-platform
cd content/hm-platform
git checkout master
cd ../..
git add content/hm-platform
git commit -m 'Update hm-platform to latest'

# Update WordPress.
# (Substitute 4.9.8 for the latest release of WordPress)
cd wordpress
git checkout 4.9.8
cd ..
git add wordpress
git commit -m 'Update WordPress to 4.9.8'

# Remove the hm-base remote:
git remote rm origin

# Add the remote for your new project:
git remote add origin git@github.com:humanmade/your-project-name.git

# Push to the new remote
git push -u origin master

If you have hm-cli installed, you should also generate a readme for the repo in our standard format:

hm project generate-readme

(You can also use the online readme creator if you prefer.)

Manually (for VIP Go projects) Manually (for VIP Go projects)

For VIP Go projects, rather than creating the codebase from scratch, you should clone the deployment repository created for you by VIP. This repo should match the VIP Go Skeleton setup, rather than our standard structure.

# Clone the VIP Go deployment repo
git clone git@github.com:wpcomvip/your-project.git your-project

# Fork and push to the development repo
cd your-project
git remote set-url origin git@github.com:humanmade/your-project.git
git push -u origin your-project

See Understanding your VIP Go Codebase for more about this setup.

If you have hm-cli installed, you should also generate a readme for the repo in our standard format:

hm project generate-readme

(You can also use the online readme creator if you prefer.)

Step 3: Enable tooling Step 3: Enable tooling

You should enable any tooling you require on the repository.

  • hm-linter: hm-linter will run the HM coding standards against all code on your repo, with minimal set up. Install it here →, or read how to install and configure the bot

  • Code Review Bot: The #dev-code-reviews bot is automatically active on all humanmade repositories. Create a “Reviewer Needed” label in your repo, and add it to PRs to have the bot handle it.

  • Travis CI/CircleCI: If you want to run unit tests or other analysis, see the guide on setting up CI. We have paid accounts for both Travis CI and CircleCI.