Terra Developer Setup

Setup

The following steps are necessary to set up Terra:

1. Install Homebrew:

   ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

2. Install Node.js:

   brew install node

3. Install grunt-cli:

   npm install -g grunt-cli

4. Install bower:

   npm install -g bower

5. Navigate to where you would like Terra files installed and clone the repo:

   git clone http://github.cerner.com/orion/terra.git

6. Go to the cloned repo.

7. If you run into a firewall or bower timeout issue, configure git to use https instead of http:

   git config url."https://".insteadOf git://

8. Install dependencies:

   npm install

9. Install browser dependencies:

   bower install

10. Install githooks and binds grunt tasks to git hooks:

    grunt githooks

    Note: This is only necessary for core contributors (someone with commit access to the main repo). For more information on what this command does, see Git Hooks Details.

    For additional grunt tasks, see our documentation

Test Terra Setup

1. Start up a local site (this can be done in a separate tab since it can run persistently): grunt build site connect

2. Go to localhost:3001/site/ to test Terra set up is complete and will get local site similar to Terra site

Git Hooks Details

Usage: Issue grunt githooks whenever an update to the githooks section of the Gruntfile occurs to ensure you are running the latest version.

Terra leverages a pre-push Git hook to:

• Ensure all tests are passing prior to merging to master.
• Ensure the blueshift.json file is up to date prior to merging to master.
• Ensure that all of the distribution files are properly built prior to merging to master.
• Update the doc site when merging to master.

Development Process

1. Run grunt build site to build the site assets and to generate the local static site.
2. In another terminal tab or window run grunt connect to start the server for the local site on port 3001.
3. Navigate to http://localhost:3001/site/
4. Repeat the following steps during development:
5. Make changes
6. Run grunt build site to build assets and update the static site.
7. Run grunt test to test your change as often as necessary.

Notes:

• The fourth step can be simplified by running grunt watch. This task will run the necessary build script(s) based on the file(s) being edited. Keep in mind that grunt build site should be run at least once prior to issuing grunt watch. It may be issued as grunt build site watch as a shortcut.
• It is not necessary to run grunt build after running grunt test since the test script will rebuild all assets.
• It is not necessary to restart the server.

Understanding Terra's Folder Structure

When working on the Terra project, a developer will typically work in the following folders:

Folder	What It Contains
src	All of Terra's source code (Less, JavaScript, etc).
examples	All of Terra's HTML examples.
docs	All of Terra's documentation.
_site	The templates used to generate the documentation site.

When viewing the contents of these files, one will notice a parallel structure behind them. This is intentional to make development and understanding easier.

For example, if we believe buttons to be an element then they belong under elements. This is true regardless of whether we are discussing Less, JS, documentation, or examples.

There is also the dev folder which is not frequently edited by developers. It is the resource which developers use to understand Terra's structure, conventions, and practices.

There are other folders which a developer will not directly edit:

Folder	What It Contains
bower_components	Third party dependencies installed by bower.
dist	Terra's compiled sources and dependencies. This is generated by grunt build and grunt dist.
node_modules	Third party dependencies installed by NPM.
site	The current local instance of the documentation site.

Ensuring Browser Compatibility

Always ensure that your work functions correctly in Chrome, FireFox, Safari, IE9, IE10, IE11 and Edge.

IE Setup

1. Install VirtualBox
2. Download virtual machine
3. Launch Virtual Box.
4. Choose ievms image from Virtual Box.
5. Open Internet Explorer.
6. Navigate to http://{your_computer_name}:3001/site

To get your_computer_name enter this in the command line: scutil --get ComputerName Network sharing must be enabled.

Check more information on IE installation

NPM/Bower

Installing and Updating NPM/Bower modules/components

When new modules need to be downloaded or old modules need to be updated for the project re-run npm install or npm install <module>. For bower components run bower install or bower install <component>.

Do not run npm update or bower update, bad things will happen.

Installing New Front-End JS Components

When installing and setting up new front-end modules (jQuery, Modernizr, etc.) the uglify:vendor grunt task will require updating. The task will need to be updated so that the files from the new components are copied and uglified into the /dist/vendor/<module> folder.