Issue #2462635: CSS overrides isn't compatible with Bootswatch themes

Issue #2348843: Add Grunt for project maintainer workflow

Conflicts:
	css/overrides.css
	includes/alter.inc

Author: markhalliwell

.gitignore

@@ -1,6 +1,14 @@
+# OS
 .DS_Store
+
+# Applications & Tools
 .idea
 bower_components
 config.codekit
 node_modules
+npm-debug.log
+
+# Project Specific
+.libraries
+lib
 starterkits/*/bootstrap

Gruntfile.js

@@ -1,83 +1,20 @@
+var path = require('path');
+
 module.exports = function (grunt) {
+  // Record grunt task execution times. Must be first.
+  require('time-grunt')(grunt);
 
-  // Project configuration.
-  grunt.initConfig({
-    pkg: grunt.file.readJSON('package.json'),
-    bower: {
-      install: {
-        options: {
-          copy: false
-        }
-      }
-    },
-    clean: {
-      css: ['css/**/*']
-    },
-    githooks: {
-      install: {
-        options: {
-          template: '.githooks.js.hbs'
-        },
-        // Change to something else once the {{ hook }} variable can be used.
-        // @see https://github.com/wecodemore/grunt-githooks/pull/40
-        'pre-commit': 'pre-commit',
-        'post-merge': 'post-merge',
-        'post-checkout': 'post-checkout'
-      }
-    },
-    less: {
-      overrides: {
-        src: 'starterkits/less/less/overrides.less',
-        dest: 'css/overrides.css',
-        options: {
-          cleancss: true,
-          compress: true
-        }
-      }
-    },
-    symlink: {
-      options: {
-        overwrite: true
-      },
-      less: {
-        src: 'bower_components/bootstrap',
-        dest: 'starterkits/less/bootstrap'
-      }
-    },
-    watch: {
-      plugin: {
-        files: ['starterkits/less/**/*.less'],
-        tasks: ['compile']
-      }
-    }
-  });
+  // Register the "default" task.
+  grunt.registerTask('default', ['compile']);
 
-  // Load the grunt plugins.
-  grunt.loadNpmTasks('grunt-contrib-clean');
-  grunt.loadNpmTasks('grunt-contrib-less');
-  grunt.loadNpmTasks('grunt-contrib-symlink');
-  grunt.loadNpmTasks('grunt-contrib-watch');
-  grunt.loadNpmTasks('grunt-bower-task');
-  grunt.loadNpmTasks('grunt-githooks');
+  // Register the "install" task.
+  grunt.registerTask('install', 'Installs or re-installs this grunt project. Read more in: MAINTAINERS.md.', ['githooks', 'sync']);
 
-  // Install tasks.
-  grunt.registerTask('install', 'Installs the grunt project. NOTE: Only needs to be ran once and should have be done automatically via npm postinstall!', function () {
-    // Install bower and setup symlinks.
-    grunt.task.run(['githooks', 'bower', 'symlink']);
+  // Load custom tasks.
+  grunt.task.loadTasks('grunt');
 
-    // Ensure there are no files in the vendor paths that may conflict with
-    // Drupal. @see https://www.drupal.org/node/2329453
-    var files = grunt.file.expand(['node_modules/**/*.info', 'bower_components/**/*.info']);
-    files.forEach(function(file) {
-      grunt.file.delete(file, { force: true });
-      grunt.log.verbose('Removed conflicting Drupal file "' + file.dest + '".');
-    });
+  // Load npm installed 'grunt-*' tasks and configurations.
+  require('load-grunt-config')(grunt, {
+    configPath: path.join(process.cwd(), 'grunt', 'config')
   });
-
-  // Compile tasks.
-  grunt.registerTask('compile', 'Compiles the base theme overrides CSS.', ['clean', 'less']);
-
-  // Default tasks.
-  grunt.registerTask('default', ['compile']);
-
 };

MAINTAINERS.md

@@ -0,0 +1,81 @@
+# Maintaining the Drupal Bootstrap Project
+
+## Prerequisites
+This project relies heavily on NodeJS/Grunt to automate some very time
+consuming tasks and to ensure effective management. If you do not have these
+CLI tools, please install them now:
+
+* https://nodejs.org
+* http://gruntjs.com
+
+## Installation
+
+This project's installation may initially take a while to complete. Please read
+through this entire README before continuing so you are aware of what to expect.
+Suffice it to say: you will not have to manually update this project again.
+
+After you have installed the prerequisite CLI tools, run `npm install` in this
+directory. This will install the necessary NodeJS modules inside the
+`node_modules` folder.
+
+After NodeJS has finished installing its own modules, it will automatically
+invoke `grunt install` for you. This is a grunt task that is specifically
+designed to keep the project in sync amongst maintainers.
+
+## Grunt
+There are several tasks available to run, please execute `grunt --help` to view
+the full list of tasks currently available. This README only covers the most
+important or commonly used tasks.
+
+### `grunt install`
+This task is automatically invoked as a `postinstall` event of `npm install`.
+There should be no need to manually invoke this task. However, if you feel the
+need to manual invoke this task, you may do so without fear of producing any
+unintended side-effects. This is simply an alias for sub-tasks defined below.
+
+### `grunt githooks`
+This is a sub-task of `grunt install`. It will automatically install the
+necessary git hooks for this project. These git hooks allow the project to keep
+track of changes to files in order to automate and ensure certain files are
+committed (e.g. compiled CSS files). Do not worry, if you already have existing
+git hook files in place, this will work around them.
+
+Any time there is a change to `package.json`, `Gruntfile.js`, `.githooks.js.hbs`
+or any of the files in the `grunt` subdirectory, the `npm install` task will
+automatically be executed by the git hook itself. This allows the workflow to
+be altered by one maintainer and those changes propagated to the others the
+next time they pull down the repository.
+
+### `grunt sync`
+This is a sub-task used by `grunt install`. It will automatically
+download and install the various 3.x.x versions of the Bootstrap and Bootswatch
+libraries for local development purposes in the `./lib` folder. This process
+utilizes Bower and can initially take a while for it to fully complete.
+
+Once you have the various versions of libraries have been installed, this task
+becomes much faster. This task utilizes the jsDelivr API to determine which
+versions to install. To avoid abusing API calls, this list is cached for one
+week as the `.libraries` file in the root of this project. In the event that a
+new list needs to be generated and the week cache expiration has not lifted,
+you can either simply remove the file manually or run `grunt sync --force` to
+force an API call and generate a new list.
+
+### `grunt compile`
+This task ensures that all the necessary variations of versions and themes of
+Bootstrap and Bootswatch are compile from `starterkits/less/less/overrides.less`.
+Typically, this task generates hundreds of files and can take upwards of
+\~10 seconds to fully complete.
+
+Optionally, if the `--dev` parameter is specified, this task will only compile
+the starterkit's `overrides.less` file for the latest version of Bootstrap: 
+* `./css/<%= latestVersion/overrides.css`
+* `./css/<%= latestVersion/overrides.min.css`
+
+### `grunt watch`
+This task is responsible for watching various source files and executing the
+appropriate tasks these source files are normally consumed by. With the caveat
+of long compilation times mentioned in the previous section, it is highly
+recommended running this task as such: `grunt watch --dev`. Keep in mind that
+this limits the rapid development of the `overrides.less` file to the default
+Bootstrap theme. If you have switched themes, you must manually compile all
+the version and theme override files.

bower.json

@@ -1,7 +1,7 @@
 {
   "name": "drupal-bootstrap",
-  "version": "7.3.0-dev",
-  "dependencies": {
-    "bootstrap": "3.3.5"
-  }
+  "version": "7.3.x-dev",
+  "license": "GPL+2",
+  "homepage": "https://www.drupal.org/project/bootstrap",
+  "private": true
 }