From c6a0f6eab9fd995caa4cfcc6e88d109fa1c99a86 Mon Sep 17 00:00:00 2001
From: Austin Pray <austin@austinpray.com>
Date: Mon, 19 Jan 2015 15:15:09 -0600
Subject: [PATCH 1/7] Reworks asset revving

fixes https://github.com/roots/roots/issues/1266
---
 .gitignore     |   1 +
 gulpfile.js    | 171 +++++++++++++++++++++++++++++++++++--------------
 lib/assets.php |   2 +-
 package.json   |   3 +-
 4 files changed, 127 insertions(+), 50 deletions(-)

diff --git a/.gitignore b/.gitignore
index 8596abe..ca018a6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@ dist
 bower_components
 node_modules
 npm-debug.log
+docs
diff --git a/gulpfile.js b/gulpfile.js
index 38e1cb4..9ca01c4 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -1,22 +1,65 @@
+// ## Globals
 /*global $:true*/
 var $        = require('gulp-load-plugins')();
 var _        = require('lodash');
 var argv     = require('yargs').argv;
 var gulp     = require('gulp');
 var lazypipe = require('lazypipe');
-var manifest = require('asset-builder')('./assets/manifest.json');
 var merge    = require('merge-stream');
 
-var mapsEnabled = !argv.production;
+// See https://github.com/austinpray/asset-builder
+var manifest = require('asset-builder')('./assets/manifest.json');
+
+// `path` - Paths to base asset directories. With trailing slashes.
+// - `path.source` - Path to the source files. default: `assets/`
+// - `path.dist` - Path to the build directory. default: `dist/`
 var path = manifest.paths;
+
+// `globs` - These ultimately end up in their respective `gulp.src`.
+// - `globs.js` - array of asset-builder js Depenency objects. Example:
+//   ```
+//   { type: 'js', name: 'main.js', globs: [] }
+//   ```
+// - `globs.css` an array of asset-builder css Depenency objects. Example:
+//   ```
+//   { type: 'css', name: 'main.css', globs: [] }
+//   ```
+// - `globs.fonts` - array of font path globs
+// - `globs.images` - array of image path globs
+// - `globs.bower` - array of all the bower main files
 var globs = manifest.globs;
+
+// `project` - paths to first-party assets.
+// - `project.js` - array of first-party js assets
+// - `project.css` - array of first-party js assets
 var project = manifest.getProjectGlobs();
 
+// CLI options
+var enabled = {
+  // Enable static asset revisioning when `--production`
+  rev: argv.production,
+  // Disable source maps when `--production`
+  maps: !argv.production
+};
+
+// Path to the compiled assets manifest in the dist directory
+var revManifest = path.dist + 'assets.json';
+
+// ## Reusable Pipelines
+// see https://github.com/OverZealous/lazypipe
+
+// ### CSS processing pipeline
+// Example
+// ```
+// gulp.src(cssFiles)
+//   .pipe(cssTasks('main.css')
+//   .pipe(gulp.dest(path.dist + 'styles'))
+// ```
 var cssTasks = function(filename) {
   return lazypipe()
     .pipe($.plumber)
     .pipe(function () {
-      return $.if(mapsEnabled, $.sourcemaps.init());
+      return $.if(enabled.maps, $.sourcemaps.init());
     })
       .pipe(function() {
         return $.if('*.less', $.less().on('error', function(err) {
@@ -39,63 +82,83 @@ var cssTasks = function(filename) {
           ]
         }
       })
+    .pipe($.rev)
     .pipe(function () {
-      return $.if(mapsEnabled, $.sourcemaps.write('.'));
-    })
-    .pipe(gulp.dest, path.dist + 'styles')
-    .pipe($.livereload)();
+      return $.if(enabled.maps, $.sourcemaps.write('.'));
+    })();
 };
 
+// ### JS processing pipeline
+// Example
+// ```
+// gulp.src(jsFiles)
+//   .pipe(jsTasks('main.js')
+//   .pipe(gulp.dest(path.dist + 'scripts'))
+// ```
+var jsTasks = function(filename) {
+  return lazypipe()
+    .pipe(function () {
+      return $.if(enabled.maps, $.sourcemaps.init());
+    })
+    .pipe($.concat, filename)
+    .pipe($.uglify)
+    .pipe($.rev)
+    .pipe(function () {
+      return $.if(enabled.maps, $.sourcemaps.write('.'));
+    })();
+};
+
+// ## Gulp Tasks
+// Run `gulp -T` for a task summary
+
+// ### Styles
+// `gulp styles` - compiles, combines, and optimizes bower css and project css.
 gulp.task('styles', function() {
   var merged = merge();
   manifest.forEachDependency('css', function (dep) {
-    merged.add(gulp.src(dep.globs)
+    merged.add(gulp.src(dep.globs, { base: path.source })
       .pipe(cssTasks(dep.name)));
   });
-  return merged;
+  return merged
+    .pipe(gulp.dest(path.dist + 'styles'))
+    .pipe($.rev.manifest(revManifest, {
+      base: path.dist,
+      merge: true
+    }))
+    .pipe(gulp.dest(path.dist));
 });
 
-gulp.task('jshint', function() {
-  return gulp.src([
-    'bower.json', 'gulpfile.js'
-  ].concat(project.js))
-    .pipe($.jshint())
-    .pipe($.jshint.reporter('jshint-stylish'))
-    .pipe($.jshint.reporter('fail'));
-});
-
-var jsTasks = function(filename) {
-  var fn = filename;
-  return lazypipe()
-    .pipe(function () {
-      return $.if(mapsEnabled, $.sourcemaps.init());
-    })
-    .pipe(function() {
-      return $.if(!!fn, $.concat(fn || 'all.js'));
-    })
-    .pipe($.uglify)
-    .pipe(function () {
-      return $.if(mapsEnabled, $.sourcemaps.write('.'));
-    })
-    .pipe(gulp.dest, path.dist + 'scripts')
-    .pipe($.livereload)();
-};
-
+// ### Scripts
+// `gulp scripts` - runs jshint then compiles, combines, and optimizes bower
+// javascript and project javascript
 gulp.task('scripts', ['jshint'], function() {
   var merged = merge();
   manifest.forEachDependency('js', function (dep) {
-    merged.add(gulp.src(dep.globs)
-      .pipe(jsTasks(dep.name)));
+    merged.add(
+      gulp.src(dep.globs, { base: path.source })
+        .pipe(jsTasks(dep.name))
+    );
   });
-  return merged;
+  return merged
+    .pipe(gulp.dest(path.dist + 'scripts'))
+    .pipe($.rev.manifest(revManifest, {
+      base: path.dist,
+      merge: true
+    }))
+    .pipe(gulp.dest(path.dist));
 });
 
+// ### Fonts
+// `gulp fonts` - grabs all the fonts and outputs them in a flattened directory
+// structure. See: https://github.com/armed/gulp-flatten
 gulp.task('fonts', function() {
   return gulp.src(globs.fonts)
     .pipe($.flatten())
     .pipe(gulp.dest(path.dist + 'fonts'));
 });
 
+// ### Images
+// `gulp images` - run lossless compression on all the images.
 gulp.task('images', function() {
   return gulp.src(globs.images)
     .pipe($.imagemin({
@@ -105,17 +168,23 @@ gulp.task('images', function() {
     .pipe(gulp.dest(path.dist + 'images'));
 });
 
-gulp.task('version', function() {
-  return gulp.src([path.dist + '**/*.{js,css}'], { base: path.dist })
-    .pipe(gulp.dest(path.dist))
-    .pipe($.rev())
-    .pipe(gulp.dest(path.dist))
-    .pipe($.rev.manifest())
-    .pipe(gulp.dest(path.dist));
+// ### JsHint
+// `gulp jshint` - lints configuration JSON and project javascript
+gulp.task('jshint', function() {
+  return gulp.src([
+    'bower.json', 'gulpfile.js'
+  ].concat(project.js))
+    .pipe($.jshint())
+    .pipe($.jshint.reporter('jshint-stylish'))
+    .pipe($.jshint.reporter('fail'));
 });
 
+// ### Clean
+// `gulp clean` - deletes the build folder entirely
 gulp.task('clean', require('del').bind(null, [path.dist]));
 
+// ### Watch
+// `gulp watch` - recompile assets whenever they change
 gulp.task('watch', function() {
   $.livereload.listen();
   gulp.watch([path.source + 'styles/**/*'], ['styles']);
@@ -126,10 +195,14 @@ gulp.task('watch', function() {
   });
 });
 
-gulp.task('build', ['styles', 'scripts', 'fonts', 'images'], function() {
-  gulp.start('version');
-});
+// ### Build
+// `gulp build` - Run all the build tasks but don't clean up beforehand.
+// Generally you should be running `gulp` instead of `gulp build`.
+gulp.task('build', ['styles', 'scripts', 'fonts', 'images']);
 
+// ### Wiredep
+// `gulp wiredep` - Automatically inject less and Sass bower dependencies. See
+// https://github.com/taptapship/wiredep
 gulp.task('wiredep', function() {
   var wiredep = require('wiredep').stream;
   return gulp.src(project.css)
@@ -138,6 +211,8 @@ gulp.task('wiredep', function() {
     .pipe(gulp.dest(path.source + 'styles'));
 });
 
+// ### Gulp
+// `gulp` - Run a complete build. To compile for production run `gulp --production`.
 gulp.task('default', ['clean'], function() {
   gulp.start('build');
 });
diff --git a/lib/assets.php b/lib/assets.php
index 12644ce..406a757 100644
--- a/lib/assets.php
+++ b/lib/assets.php
@@ -22,7 +22,7 @@ function asset_path($filename) {
     return get_template_directory_uri() . '/dist/' . $filename;
   }
 
-  $manifest_path = get_template_directory() . '/dist/rev-manifest.json';
+  $manifest_path = get_template_directory() . '/dist/assets.json';
 
   if (file_exists($manifest_path)) {
     $manifest = json_decode(file_get_contents($manifest_path), true);
diff --git a/package.json b/package.json
index 327b37c..b434ae5 100644
--- a/package.json
+++ b/package.json
@@ -18,6 +18,7 @@
   ],
   "scripts": {
     "build": "bower install && gulp",
+    "docs": "docco gulpfile.js",
     "jshint": "gulp jshint"
   },
   "engines": {
@@ -39,7 +40,7 @@
     "gulp-pleeease": "^1.1.0",
     "gulp-plumber": "^0.6.3",
     "gulp-rename": "^1.2.0",
-    "gulp-rev": "^2.0.1",
+    "gulp-rev": "^3.0.0",
     "gulp-sass": "^1.2.4",
     "gulp-sourcemaps": "^1.1.1",
     "gulp-uglify": "^1.0.1",

From 37f8a2646ff781ce59232aa7530c728ad811b471 Mon Sep 17 00:00:00 2001
From: Austin Pray <austin@austinpray.com>
Date: Mon, 19 Jan 2015 15:25:27 -0600
Subject: [PATCH 2/7] docs -> docco

---
 .gitignore   | 2 +-
 package.json | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index ca018a6..35422a0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,4 +4,4 @@ dist
 bower_components
 node_modules
 npm-debug.log
-docs
+docco
diff --git a/package.json b/package.json
index b434ae5..11dc5d6 100644
--- a/package.json
+++ b/package.json
@@ -18,7 +18,7 @@
   ],
   "scripts": {
     "build": "bower install && gulp",
-    "docs": "docco gulpfile.js",
+    "docs": "docco -o docco gulpfile.js",
     "jshint": "gulp jshint"
   },
   "engines": {

From c60b9052bf213d910ddceea6a4c4c5bc83ec42ff Mon Sep 17 00:00:00 2001
From: Austin Pray <austin@austinpray.com>
Date: Fri, 23 Jan 2015 02:57:17 -0600
Subject: [PATCH 3/7] Enhance asset revving

conditional asset revving based on --production
make assets.php respect new asset revving flow
---
 gulpfile.js    | 41 +++++++++++++++++++++++++----------------
 lib/assets.php | 13 ++++++++++---
 2 files changed, 35 insertions(+), 19 deletions(-)

diff --git a/gulpfile.js b/gulpfile.js
index 9ca01c4..6424eb6 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -82,7 +82,9 @@ var cssTasks = function(filename) {
           ]
         }
       })
-    .pipe($.rev)
+    .pipe(function () {
+      return $.if(enabled.rev, $.rev());
+    })
     .pipe(function () {
       return $.if(enabled.maps, $.sourcemaps.write('.'));
     })();
@@ -102,12 +104,29 @@ var jsTasks = function(filename) {
     })
     .pipe($.concat, filename)
     .pipe($.uglify)
-    .pipe($.rev)
+    .pipe(function () {
+      return $.if(enabled.rev, $.rev());
+    })
     .pipe(function () {
       return $.if(enabled.maps, $.sourcemaps.write('.'));
     })();
 };
 
+// ### Write to Rev Manifest
+// If `--production` then write the revved assets to the manifest.
+var writeToManifest = function (directory) {
+  return lazypipe()
+    .pipe(gulp.dest, path.dist + directory)
+    .pipe(require('gulp-debug'))
+    .pipe($.livereload)
+    .pipe($.rev.manifest, revManifest, {
+      base: path.dist,
+      merge: true
+    })
+    .pipe(require('gulp-debug'))
+    .pipe(gulp.dest, path.dist)();
+};
+
 // ## Gulp Tasks
 // Run `gulp -T` for a task summary
 
@@ -116,16 +135,11 @@ var jsTasks = function(filename) {
 gulp.task('styles', function() {
   var merged = merge();
   manifest.forEachDependency('css', function (dep) {
-    merged.add(gulp.src(dep.globs, { base: path.source })
+    merged.add(gulp.src(dep.globs)
       .pipe(cssTasks(dep.name)));
   });
   return merged
-    .pipe(gulp.dest(path.dist + 'styles'))
-    .pipe($.rev.manifest(revManifest, {
-      base: path.dist,
-      merge: true
-    }))
-    .pipe(gulp.dest(path.dist));
+    .pipe(writeToManifest('styles'));
 });
 
 // ### Scripts
@@ -135,17 +149,12 @@ gulp.task('scripts', ['jshint'], function() {
   var merged = merge();
   manifest.forEachDependency('js', function (dep) {
     merged.add(
-      gulp.src(dep.globs, { base: path.source })
+      gulp.src(dep.globs)
         .pipe(jsTasks(dep.name))
     );
   });
   return merged
-    .pipe(gulp.dest(path.dist + 'scripts'))
-    .pipe($.rev.manifest(revManifest, {
-      base: path.dist,
-      merge: true
-    }))
-    .pipe(gulp.dest(path.dist));
+    .pipe(writeToManifest('scripts'));
 });
 
 // ### Fonts
diff --git a/lib/assets.php b/lib/assets.php
index 406a757..3589f06 100644
--- a/lib/assets.php
+++ b/lib/assets.php
@@ -18,8 +18,10 @@ namespace Roots\Sage\Assets;
  * - You're not logged in as an administrator
  */
 function asset_path($filename) {
+  $dist_path = get_template_directory_uri() . '/dist/';
+
   if (WP_ENV === 'development') {
-    return get_template_directory_uri() . '/dist/' . $filename;
+    return $dist_path . $filename;
   }
 
   $manifest_path = get_template_directory() . '/dist/assets.json';
@@ -30,8 +32,13 @@ function asset_path($filename) {
     $manifest = [];
   }
 
-  if (array_key_exists($filename, $manifest)) {
-    return get_template_directory_uri() . '/dist/' . $manifest[$filename];
+  $directory = dirname($filename) . '/';
+  $file = basename($filename);
+
+  if (array_key_exists($file, $manifest)) {
+    return $dist_path . $directory . $manifest[$file];
+  } else {
+    return $dist_path . $directory . $file;
   }
 }
 

From d5d2d02459d19727f17705c271eb7e0b4e3ee936 Mon Sep 17 00:00:00 2001
From: Austin Pray <austin@austinpray.com>
Date: Sat, 24 Jan 2015 13:17:11 -0600
Subject: [PATCH 4/7] Fixes livereload

If the environment is development -> try loading the livereload client
being served by `gulp watch`
---
 gulpfile.js    |  2 --
 lib/assets.php | 21 +++++++++++++--------
 2 files changed, 13 insertions(+), 10 deletions(-)

diff --git a/gulpfile.js b/gulpfile.js
index edd2ff9..7cc0e5c 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -118,13 +118,11 @@ var jsTasks = function(filename) {
 var writeToManifest = function(directory) {
   return lazypipe()
     .pipe(gulp.dest, path.dist + directory)
-    .pipe(require('gulp-debug'))
     .pipe($.livereload)
     .pipe($.rev.manifest, revManifest, {
       base: path.dist,
       merge: true
     })
-    .pipe(require('gulp-debug'))
     .pipe(gulp.dest, path.dist)();
 };
 
diff --git a/lib/assets.php b/lib/assets.php
index 6aa0c11..60c50ef 100644
--- a/lib/assets.php
+++ b/lib/assets.php
@@ -19,10 +19,8 @@ namespace Roots\Sage\Assets;
  */
 function asset_path($filename) {
   $dist_path = get_template_directory_uri() . '/dist/';
-
-  if (WP_ENV === 'development') {
-    return $dist_path . $filename;
-  }
+  $directory = dirname($filename) . '/';
+  $file = basename($filename);
 
   $manifest_path = get_template_directory() . '/dist/assets.json';
 
@@ -32,10 +30,7 @@ function asset_path($filename) {
     $manifest = [];
   }
 
-  $directory = dirname($filename) . '/';
-  $file = basename($filename);
-
-  if (array_key_exists($file, $manifest)) {
+  if (WP_ENV !== 'development' && array_key_exists($file, $manifest)) {
     return $dist_path . $directory . $manifest[$file];
   } else {
     return $dist_path . $directory . $file;
@@ -59,6 +54,15 @@ function assets() {
     add_filter('script_loader_src', __NAMESPACE__ . '\\jquery_local_fallback', 10, 2);
   }
 
+  /**
+   * Livereload client
+   * https://github.com/livereload/livereload-js
+   */
+  if (WP_ENV === 'development') {
+    wp_register_script('livereload', 'http://localhost:35729/livereload.js?snipver=1', null, false, true);
+    wp_enqueue_script('livereload');
+  }
+
   if (is_single() && comments_open() && get_option('thread_comments')) {
     wp_enqueue_script('comment-reply');
   }
@@ -115,3 +119,4 @@ function google_analytics() {
 if (GOOGLE_ANALYTICS_ID) {
   add_action('wp_footer', __NAMESPACE__ . '\\google_analytics', 20);
 }
+

From 55367f4106c93ece949b3c613d31b7516ec45ddf Mon Sep 17 00:00:00 2001
From: Austin Pray <austin@austinpray.com>
Date: Sat, 24 Jan 2015 13:57:44 -0600
Subject: [PATCH 5/7] Updates rev documentation

---
 gulpfile.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/gulpfile.js b/gulpfile.js
index 7cc0e5c..9e418f8 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -114,7 +114,8 @@ var jsTasks = function(filename) {
 };
 
 // ### Write to Rev Manifest
-// If `--production` then write the revved assets to the manifest.
+// If there are any revved files then write them to the rev manifest.
+// See https://github.com/sindresorhus/gulp-rev
 var writeToManifest = function(directory) {
   return lazypipe()
     .pipe(gulp.dest, path.dist + directory)

From e45dc36736c61567301bca901fca8baaa9c89edd Mon Sep 17 00:00:00 2001
From: Austin Pray <austin@austinpray.com>
Date: Sat, 24 Jan 2015 14:04:48 -0600
Subject: [PATCH 6/7] Update .gitignore

---
 .gitignore | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 35422a0..8596abe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,4 +4,3 @@ dist
 bower_components
 node_modules
 npm-debug.log
-docco

From a3040c496ab439e3f7566101663bdc89283500fb Mon Sep 17 00:00:00 2001
From: Austin Pray <austin@austinpray.com>
Date: Sat, 24 Jan 2015 14:05:02 -0600
Subject: [PATCH 7/7] Update package.json

---
 package.json | 1 -
 1 file changed, 1 deletion(-)

diff --git a/package.json b/package.json
index d68460c..710e721 100644
--- a/package.json
+++ b/package.json
@@ -18,7 +18,6 @@
   ],
   "scripts": {
     "build": "bower install && gulp",
-    "docs": "docco -o docco gulpfile.js",
     "jshint": "gulp jshint",
     "jscs": "jscs gulpfile.js assets/scripts/*.js"
   },