Development Guidelines

• Theme styles use SCSS and are stored in assets/src/styles.
• Theme JavaScript files are in assets/src/scripts.
• Theme Images files are in assets/src/images.

The theme uses gulp to run various tasks such as compiling CSS, bundling JS and minifiying images.

• Compiled/proccessed files are not tracked in git and MUST be built locally and on deploy.
• All compiled/proccessed assets are be kept in assets/dist.
• Always load assets from assets/dist, you probably shouldn't be loading anything from assets/src.

Releasing a new version.

It is essential that whenever a new version is released, we increment the version number in the theme stylesheet (style.css). This is used to version all theme assets, and bumping this is necessary to ensure nobody gets cached files. This also includes the cached asset integrity hash used by the Altis browser security module, and without the change, assets may fail to load.

Dev Setup

Dependencies

• A development environment and working WordPress install. e.g. Salty Wordpress
• Git
• NPM
• Gulp CLI

Getting it set up

1. Clone the repository to the themes directory of your WordPress install. git clone --recursive git@github.com:humanmade/hm-handbook-theme.git
2. If you didn't pass --recursive when cloning in the previous step, you need to make sure you run git submodule update --recursive --init from inside the hm-handbook-theme directory to pull down the submodules that are used in this theme.
3. npm install to install all required dependencies.
4. gulp to run all the tasks required to build the theme.
5. gulp watch to watch for changes, and run required tasks automatically.

Updating HM Pattern Library

The pattern library is a submodule checked out to /vendor/hm-pattern-library. We are using the compiled version of this so you should check out either a tagged release or the gh-pages branch when updating.

Example of what needs to be done:

1. cd vendor/hm-pattern-library
2. git fetch --tags && git checkout 1.0 or git checkout gh-pages && git pull
3. cd ../../ && git add vendor/hm-pattern-library && commit -m 'Update HM Pattern Library'