Skip to content

Latest commit

 

History

History
231 lines (130 loc) · 7.65 KB

SETUP.md

File metadata and controls

231 lines (130 loc) · 7.65 KB
Raw

Set up the digital pattern library

Version 0.4 Last updated: Monday 6 December 2016

This is a guide to get your environment set up to contribute to the digital pattern library.

1. Prerequisites

Git

The digital pattern library code is stored in a Git repository, so you will need a Git client to clone it to your local machine and commit changes back to the repository.

If you are a Windows user, we recommend that you always install the Git command line client, as this will allow you to right-click within a folder and select "Git Bash Here" to open a command-line prompt. You can use this to run Git, Node, Grunt, and Ruby commands.

There are also a number of GUI clients available; our favourites, in order, are:

Node.js

The digital pattern library uses Grunt, the JavaScript task runner, to automate the build process. Grunt is built on Node.js which is a JavaScript runtime that uses Google Chrome's V8 JavaScript engine. If you're not familiar with either of these see Getting started with Grunt for the basics.

To install Node.js:

  1. Visit http://nodejs.org/
  2. Download the latest stable release.
  3. Run the installer.

Grunt CLI

Next install the Grunt command line interface (CLI). Open a "Node.js command prompt" (Windows), Terminal (OS X), or shell (*nix) and run the following command:

$ npm install -g grunt-cli

Ruby

We also use Compass to compile Sass code to CSS. This requires Ruby.

Install Ruby on Windows

The easiest way to install Ruby is with RubyInstaller for Windows.

When prompted at the beginning of the installation make sure to check the box with the label "Add Ruby executables to your PATH". This will mean that you can run commands like gem install ....

Once you're finished with the installation, you should close and reopen any command prompts that you have since they will need to get the updated PATH with Ruby added.

Install Ruby on MacOS X

Recent versions of MacOS X already have Ruby installed, no further installation is required.

2. Initialize developer tools

Clone the repository

Clone the Git repository into a folder on your computer using your Git client, or at the command line:

git clone https://github.com/standrewsdigital/digital-pattern-library.git

Install Grunt dependencies

  1. At the command line, navigate to the folder containing your local clone of the pattern library.

        $ cd path/to/folder

    Where path/to/folder is the path to the folder you cloned the pattern library locally. (Or in Windows right-click within the folder containing your local clone of the pattern library and select 'Git Bash'.)

  2. Install the dependencies for building the pattern library using the Node package manager, npm. The package.json file defines what dependencies are installed.

     $ npm install

Error: Unable to connect to github.com

If you get an error such as

npm ERR! Error: Command failed: fatal: unable to connect to github.com:

it may be that you are behind a firewall and need to use https instead of git and git+ssh. Append the following to your .gitconfig file:

# Use https instead of git and git+ssh
[url "https://github.com/"]
        insteadOf = git://github.com/
[url "https://github.com/"]
        insteadOf = git@github.com:

You can always find the location of your .gitconfig file by typing the following command into a command prompt: git config --global --edit.

(On Windows, to exit this editor press Ctrl+C, then type :quit and press Enter.)

Install Compass Ruby gem

Install the Compass Ruby gem to compile Sass code into CSS.

$ gem install compass

Conclusion

You should now be configured to start work on the pattern library. You should now read CONTRIBUTING.md for some guidelines and principles of development.

3. Update an existing install

If you already have the DPL installed and need to update the underlying packages start here:

1. Make sure your Node.js version is up-to-date.

To find out which version you have, run node -v using Git Bash or the command line.

Update to version 6.9.1 LTS if you don't already have it from http://nodejs.org/. All the default installation options work so there is no need to change them.

2. Checkout the branch from GitHub.

Use your prefered Git client to checkout the branch containing the updated package.json files.

3. Delete the node_modules folder.

This can be found within the root of the DPL folder. This may take a long time due to the size of these files.

4. Reinstall npm to your DPL directory.

Run npm install using Git Bash or the command line.

5. Verify it works.

Run grunt and if it works then you're successfully updated.

4. Troubleshooting

Error: handlebars does not support render

If you get the following error when running Grunt:

Running "assemble:core_meta" (assemble) task
handlebars does not support render.
Assembling core/build.json ERROR
Warning: handlebars does not support render. Use --force to continue.

Aborted due to warnings.

it may be that npm install did not complete. It has been reported on Stack Overflow that sometimes node doesn't recursively install the modules for assemble-handlebars; this is a known issue in grunt-assemble, issue #31.

You can easily test for this by adding a pre-release identifier to the version number in package.json, e.g.

"version": "0.9.0-alpha",

If grunt breaks after adding this, do the following:

  1. At the command line (e.g. using Git Bash) navigate to node_modules/assemble-handlebars.
  2. Run npm install.
  3. The remaining modules will install.
  4. Run grunt – it should complete successfully now.