Grunt
=====

Grunt is used in Totara LMS to process JavaScript, CSS and less files,
it should be executed after every modification of files in this format.

Please note you need to purge all your caches to see your changes
or perform an upgrade triggered by a version bump.


Installation
============

1. Install Node.js and npm in your OS - minimum recommended version of npm is v2.15
2. run 'npm install' in the root directory to install all required npm modules in expected versions
3. either install grunt-cli globally using 'npm install grunt-cli -g' (you may be required to use sudo)
4. or install grunt locally via 'npm install grunt-cli' (you will have to use './node_modules/.bin/grunt' later)


Execution
=========

* Run 'grunt' from the root directory to execute all tasks in all plugins and core
* Run 'grunt' from a plugin directory to execute tasks for one plugin only (note that this may be buggy)
* Run 'grunt watch' from the root directory to execute tasks for modified files automatically


Shrink-wrapping of npm modules
==============================

npm-shrinkwrap.json file specifies what npm module versions should be used by
all developers. This file must be recreated after every modification of package.json file.

Ideally the npm modules should be updated in all branches at the same time
to minimise problems when switching branches in one checkout.

Totara employees should use the following procedure:

1. make sure you have latest Node.js v4 with latest npm@2 installed
2. run 'grunt' and make sure everything is up-to-date before you start
3. delete node_modules/ directory
4. delete npm-shrinkwrap.json file
5. run 'npm install'
6. run 'npm shrinkwrap --dev'
7. run 'grunt'
8. verify the changes in minified JavaScript and CSS are ok
9. commit the changed files
10. switch to Node.js v6 with npm@3
11. delete node_modules/ directory
12. run 'npm install'
13. verify there are no changed files
14. submit patch for review
15. remind developers in changelog they need to 'npm install' when switching branches or updating


Steps for homebrew on OSX
=========================

1. brew uninstall all node versions
2. use 'brew edit node@4' to remove the --without-npm from the make step
3. use 'brew install node@4 --without-npm'
4. add node bin directory to your path
5. check the npm version is v2.15
