Adding blt extension docs.

INSTALL.md

@@ -133,4 +133,4 @@ Note that all common project tasks are executed through `blt`. For a full list o
 
 ## Next Steps
 
-Now that your new project works locally, read through the new [README.md](https://github.com/acquia/blt/blob/8.x/template/README.md) file in your project to learn how to perform common project tasks and integrate with third party tools.
+Now that your new project works locally, read through the new [README.md](https://github.com/acquia/blt/blob/8.x/template/README.md) file in your project to learn how to perform common project tasks and integrate with third party tools.

index.md

@@ -2,6 +2,14 @@
 
 Welcome to the BLT documentation site! Please read through the [Quick Start Guide](https://github.com/acquia/blt/INSTALL.md) to get started, and then browse the rest of this project's documentation in the sidebar.
 
+# Documentation structure
+
+BLT Documentation is broken into the following top-level segments:
+
+* Overview - Information about BLT
+* Getting started - How to add BLT to your project
+* Project documentation - Templated documentation that will be added to your BLTed project. 
+
 # Contributing to BLT
                                        
 Please feel free to edit any of the pages in this documentation via the 'Edit on GitHub' link at the top right. If you would like to help improve BLT, please file issues via the GitHub issue queue. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and instructions.

mkdocs.yml

@@ -37,4 +37,5 @@ pages:
           - Release notes: 'scripts/release-notes/README.md'
         - Setting up continuous integration: 'template/readme/ci.md'
         - Open source contribution: 'template/readme/os-contribution.md'
+  - Extending / Overriding BLT: 'template/readme/extending-blt.md'
   - Contributing: 'CONTRIBUTING.md'

scripts/blt/convert-to-composer.sh

@@ -59,7 +59,11 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
   echo ""
   echo "* Restart your terminal session to register your new blt alias."
   echo "* Review your codebase and commit the desired changes."
-  echo "* Integrate your custom Phing files by adding their file paths to project.yml under the 'imports' key."
+  echo "* If you have a custom Phing build file, you will likely need to update it and add it to project.yml under the 'import' key. See readme/extending-blt.md."
+  echo "* If you are not using Lightning, remove lightning-specific target-hooks from project.yml."
+  # .travis.yml
+  # hash salt in settings.php
+  # readme overrides
 
 else
   exit 1

template/.travis.yml

@@ -46,12 +46,11 @@ install:
   - composer validate --no-check-all --ansi
   - composer install
   - export PATH=$TRAVIS_BUILD_DIR/vendor/bin:$PATH
-  - drupal init --quiet
+  # Initialize drupal console default configuration.
+  - drupal init
   # Install proper version of node for front end tasks.
   - nvm install 4.4.1
   - nvm use 4.4.1
-  # Initialize drupal console default configuration.
-  - drupal init
 
 before_script:
   # Clear drush release history cache, to pick up new releases.

template/readme/best-practices.md

@@ -82,8 +82,7 @@ See the [Drupal 8 Cache API](https://www.drupal.org/developing/api/8/cache) docu
 
 ## Patching
 
-All modifications to contributed code should be performed via a patch. For detailed information on how to patch projects, please see [../patches/README.md]
-(../patches/README.md)
+All modifications to contributed code should be performed via a patch. For detailed information on how to patch projects, please see [../patches/README.md](../patches/README.md)
 
 ## Views
 

template/readme/extending-blt.md

@@ -0,0 +1,39 @@
+# Extending / Overriding BLT
+
+To add or override a Phing target, you may create a custom build file. You must specify the location of your custom build file using the `import` key to your project.yml file.
+
+## Adding a custom target
+
+      <project name="custom" default="build">
+        <!-- Add custom targets. -->
+      </project>
+
+## Overriding an existing target
+
+To override an existing target, just give it the same name as the default target provided by BLT. E.g.,
+
+      <project name="custom" default="build">
+        <patternset id="files.frontend">
+          <include name="**/*.js"/>
+          <!-- Ignore custom bootstrap_sass directory. -->
+          <exclude name="**/bootstrap_sass/**/*"/>
+        </patternset>
+      </project>
+
+## Overriding a variable value: 
+
+You can override the value of any Phing variable used by BLT by either:
+
+1. Adding the variable to your project.yml file:
+
+        behat.tags: @mytags
+
+2. Specifying the variable value in your `blt` command using [Phing](https://www.phing.info/docs/stable/hlhtml/index.html#d5e792) argument syntax `-D[key]=[value]`, e.g.,
+
+        blt tests:behat -Dbehat.tags='@mytags'
+        
+3. Using a custom build properties file rather than project.yml:
+
+        blt tests:behat -propertyfile mycustomfile.yml -propertyfileoverride
+
+

template/scripts/git-hooks/pre-commit

@@ -12,6 +12,5 @@ if [ ! -f $PHPCS_BIN ];
     echo "Sniffing staged files via PHP Code Sniffer."
 fi
 
-
-${ROOT_DIR}blt.sh validate:phpcs:files -Dfiles="$LIST" -q
+${ROOT_DIR}/vendor/bin/blt validate:phpcs:files -Dfiles="$LIST" -q
 exit 0;