#gulp-runner-tdp

##Overview
(Yet another) Gulp-based task-runner. The main advantages (over most usage of Gulp I have seen) are:

• Your gulp tasks can (really) easily be reusable plugins - as NPM modules
  • No more copy/paste of your gulpfile from one project to the next - backport your fixes/improvements to all your projects!
  • Plugins are just common JS modules (regular NPM modules) with no extra code required (so you probably already have them)
  • This encourages plugins/tasks to do one task only (and hopefully therefore) to do it well - the unix philosophy
• It's really easy to keep customisations to your gulp tasks configurations in source control for your project
  • There's a helper library which makes it really easy to preferentially load your plugin config from your source-controlled files with automatic fallback to the default config file (the helper also provides a simple way to copy your config file to the project root on npm install etc.)

##Semver
This project aims to maintain the semver version numbering scheme.

##Changelog
See the changelog file

##Requirements

• Node runtime - either:
  • Node >= 0.11
  • IOJS >= 1.0
• Installation:
  • NPM
  • Git/GitHub
• gulp (obviously!)

##NPM/Node package dependencies
###Production

• require-dir - require files from a directory
• winston - logging library
• mkdirp - recursively create directories

###development

• mocha - Test runner
• coveralls - Code coverage analysis reporter
• istanbul - Code coverage
• mocha-lcov-reporter - Code coverage

##Installation
###Via NPM (usually the simplest way)
Installation is super simple, in your command line terminal, just cd to your project root and run:

npm install gulp-runner-tdp gulp --save-dev

It is recommended to list gulp, gulp-runner-tdp and all required plugins in your project's package.json file - usually this would be in the devDependencies section as users won't typically need to run this in production.

###Via Git(Hub)

git clone https://github.com/neilstuartcraig/gulp-runner-tdp.git
npm install
npm install gulp

You may then want to add gulp and gulp-runner-tdp to your package.json file.

Also ensure that you have gulp installed locally in the project you're developing. To achieve this, you can run e.g. npm install gulp --save-dev in your project root or simply include both gulp-runner-tdp and gulp in your NPM package.json file.

You will also need to include all the gulp-runner-tdp plugins you require (these add gulp tasks - see below for more details).

##Usage Runtime usage of gulp-runner-tdp is the same as native gulp, namely you can simply run:

gulp <task-name>[ <task-name-2> <task-name-3> ...]

(where the tasks are defined via plugins)

NOTE: If you want to chain tasks in a reliable order or create complex parallel/series configurations, you may wish to consider a gulp plugin called gulp-sequence

##Configuration files and source control When you install gulp-runner-tdp, the NPM post-install script creates a directory called gulp-runner-tdp in your project root. This directory contains another directory called config into which the installer copies the default gulp-runner-tdp configuration file (gulp-runner-tdp-core-config.js). This is the highest priority configuration file for gulp-runner-tdp (so it'll be used by default when you run gulp-runner-tdp via gulp <task-name-X>) and is intended to be modified to suit your project and to be saved in your source control repository along with your project code.

You can place gulp-runner-tdp plugin configuration files into the same (<project root>/gulp-runner-tdp/config/) directory. By convention, gulp-runner-tdp plugins should install their default configuration file(s) and use these project-local configuration file(s) as their highest priority - this allows you to source-control your plugin configurations easily too.

It is recommended to follow the regular node convention of excluding the node_modules directory from your source control via e.g. .gitignore.

##Plugins (tasks) Tasks are added via the addition of plugins, these are separate npm modules - keeping them distinct and dedicated. Plugins can define any number of tasks and simply use standard gulp syntax for adding tasks, e.g.:

var gulp=require("gulp");
gulp.task("some-task", function()
{
  // task logic goes here
});

The convention is that your plugin npm package has a directory/folder in its root called "tasks" - task files must be stored here as .js files. gulp-runner-tdp will load all the .js files present in this directory for each of the plugins it finds and will make all tasks defined in these files available to be run via gulp.

Once your project npm is installed (providing you have adhered to the above), you can then run the above task via:

gulp some-task

###Plugin creation guide
To create a plugin, probably the simplest starter is to look at one of the plugins below. As a more general guide though, you would need to create a project (ideally an npm package) which:

• Has a directory/folder called "tasks" in the root directory - tasks must be stored in this directory/folder
• Has one or more tasks (you can define one or more tasks per file) which simply define standard gulp tasks
• Installs necessary files (e.g. configuration) into the project root to enable users to source-control their configuration files - since this is the purpose of this plugin. This should be done in the npm postinstall phase
• Can optionally make use of gulp-runner-tdp-plugin-helper-lib to help with creating installers

###Available plugins

• gulp-runner-tdp-plugin-build-js - a javascript build task
• gulp-runner-tdp-plugin-build-css - a CSS build task

##Known issues
None currently

##Tests
There are some built-in tests which use Mocha, you can run these (after installation) via:

npm test

All test should pass - we use Travis CI to verify this with each push to the GitHub master branch.

##Bugs
If you find a bug, please let me know via an issue.

##Contributing
If you have ideas for improvements or want to contribute a bug fix, please create an issue first so we can discuss and make sure we don't duplicate efforts and that the idea is in the right direction for the plugin.

##License
This plugin is released under an MIT license. Please drop me a line if you use the plugin so I have an idea of usage.