### Running Gulp [Gulp](http://gulpjs.com/) is a build program written in JavaScript and running on Node. You will be using Gulp to build JS code for concatenating files, linting those files, minifying code, running tests, and performing other tasks. Please take a look at Gulp's [simple API](https://github.com/gulpjs/gulp/tree/master/docs) before starting. #### 0. Overview: how this thing works The recommended usage for Gulp is to have it continuously 'watching' your scripts as you code. When you update a file, Gulp will notice the change and rebuild your code immediately to a target directory. Each JS project is considered to be an `app`. An app is a Backbone or Chaplin file that lives in the `/js/apps` directory. So, for example, the `accounting` app is `/js/apps/accounting.js`. It is basically your `main` file, from which all your app's code will be included. When running, gulp will build out a concatenated dev file of your app and place it in `/public/js/dev/{your_app_name}.js`. When you are ready to push code to production you must specifically build the code with the `gulp deploy` command. This will be covered below. #### 1. Directory layout Gulp will be writing your JS files to a target directory. In other words, none of the files in the frontend folder will be served by a web server directly, and must be served from their built, concatenated versions instead. Just running the default gulp task will write the dev versions, but if you want the minified versions that are used in production you must run ```bash gulp deploy ``` The directory layout in the codebase for these js files looks like ```bash - /public - /js +/dev +/releases ``` #### 2. Configuration All you need to get started is creat a config.json file in the `/frontend/config` folder that looks like the following: ```json { "app": "accounting", //the name of your app. No '.js' or '.scss' needed } ``` The app name will be used for naming all built files and should correspond to the js or scss app file you are building from. Keep in mind OA and ALW both use `/public/js/dev` and `/public/js/releases` for development and production code, respectively. Gulp will add these values to your path. If you'd like to also use Chaplin in your app with a Chaplin controller, you will need to have your controller named consistently with your app name. For example, if your app is "analytics" your controller should be in the `frontend/js/controllers` folder and named `analytics_controller.js`. If named in this way, the default gulp task will automatically include the controller. #### 3. Start Gulp Now you are ready to get started. First, check your configuration by running: ```bash $ gulp setup ``` If everything works, you should see something like this: ```bash [15:51:49] Using gulpfile /Users/jviletto/Sites/orchard/frontend/gulpfile.js [15:51:49] Starting 'setup'... [15:51:49] Finished 'setup' after 231 μs ``` Now you can start gulp: ```bash $ gulp ``` This will start the watcher. As you begin coding, keep the Terminal window open in the background or on another screen. Whenever you save a file, gulp will rebuild your files on the fly. This should take about a second to complete. #### 4. Devolping SASS The frontend folder also supports the development of scss in addition to js files. The process for this works much in the same was as .js development. In the `/style-redesign/applications` folder, you should create a .scss file named in accordance with the "app" value in your config file. You can then have gulp watch for .scss changes and automatically build out the corresponding .css by running: ```bash $ gulp style-redesign # or if you prefer without watching $ gulp style-build-redesign ``` #### 5. Linting and tests When deploying code, jshint will automatically run to enforce certain coding conventions and styles. If there are any failures or problems with your code, Gulp will notify you at this time. If you would like to run this process manually, you can trigger hinting at any time by running: ```bash $ gulp hint ``` Please note that this process does not currently restrict itself to only the files in your app. Instead, all of our js files (minus libraries and modules) get hinted during this process. The requirement to have unit-tested code also applies to work done in the frontend folder. Unit tests live in `/frontend/test` and will then have a directory named for the testing library being used. Currently, all javascript unit tests are written in Mocha and thus live in the `frontend/test/mocha` folder. Documentation on Mocha can be found [here](http://visionmedia.github.io/mocha/). Additionally, we are using Chai's Assert library for Mocha testing assertions. Documentation on this library can be found [here](http://chaijs.com/api/assert/). All code needs to pass all tests and the linter in order for it to be ready for production. Failing code *must not* be committed. #### 6. Deploying Code When you're all set to get your code deployable and ready for a Pull Request, you must first run your gulp build task as normal. You must then run the following command: ```bash $ gulp deploy ``` This command will create a timestamped, minified version of your code in the release folder. This is the file that will actually be served in production. Only the most recent version of a built file gets used, so having the old versions of built apps will not interfere. However, it is good practice to remove the old built file when deploying a new one. Additionally, a minified (non-timestamped) dev file will get created during this process.