Adding blt extension docs. (#272)

* Adding blt extension docs.

* Removing docs from template.

Author: grasmash

INSTALL.md

@@ -107,11 +107,11 @@ Note that all of the steps from this point forward are the same steps that would
 
 Before building your project dependencies and installing Drupal, you must have a fully functional \*AMP stack on your local machine. BLT intentionally does not provide this local development environment--that is outside of the scope of BLT’s intended responsibilities. It does, however, make recommendations for which tools you should use to manage your stack.
 
-Please see [Local Development](template/readme/local-development.md) for more information on setting up your \*AMP stack:
+Please see [Local Development](docs/local-development.md) for more information on setting up your \*AMP stack:
 
-* [Acquia Dev Desktop](template/readme/local-development.md#using-acquia-dev-desktop-for-blt-generated-projects)
-* [Drupal VM](template/readme/local-development.md#using-drupal-vm-for-blt-generated-projects)
-* [Other](https://github.com/acquia/blt/blob/8.x/template/readme/local-development.md#alternative-local-development-environments)
+* [Acquia Dev Desktop](docs/local-development.md#using-acquia-dev-desktop-for-blt-generated-projects)
+* [Drupal VM](docs/local-development.md#using-drupal-vm-for-blt-generated-projects)
+* [Other](https://github.com/acquia/blt/blob/8.x/docs/local-development.md#alternative-local-development-environments)
 
 When you have completed setting up your local \*AMP stack, double check that the following pieces of information are still correct:
 

README.md

@@ -43,12 +43,12 @@ It scope is discretely defined. It is *not* intended to provide:
 * [Testing Framework](template/tests).
     * Behat: default `local.yml` configuration, example tests, `FeatureContext.php`
     * PHPUnit: default tests for ensuring proper functioning of BLT provided components
-* [Project tasks](template/readme/project-tasks.md)
+* [Project tasks](docs/project-tasks.md)
     * Executing tests and validating code
     * Building dependencies
     * (Re)installation of Drupal
     * Production-safe artifact generation and deployment
-* [Continuous Integration](template/readme/ci.md)
+* [Continuous Integration](docs/ci.md)
     * Travis CI
     * GitHub
 

template/readme/acsf-setup.md docs/acsf-setup.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/architecture.md docs/architecture.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/readme/best-practices.md docs/best-practices.md

@@ -1,7 +1,7 @@
 [Acquia BLT (Build and Launch Tool)](https://github.com/acquia/blt) generates new Drupal projects using a standardized template derived from Acquia Professional Services' best practices.
 
 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.
-                                       
+
 # 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.

template/readme/ci.md docs/ci.md

@@ -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'

template/readme/code-review.md docs/code-review.md

@@ -22,6 +22,7 @@
     <!-- @todo Do not overwrite structured or executable files. Instead, update them intelligently. composer.json, project.yml, settings.php, drush.wrapper etc. -->
     <exec dir="${repo.root}" command="rsync -a --no-g --no-p --update ${blt.root}/template/ ${repo.root}/ --exclude 'project.yml' --exclude 'composer.json'" logoutput="true" checkreturn="true"/>
     <exec dir="${repo.root}" command="rsync -a --no-g --no-p --update ${blt.root}/template/project.yml ${repo.root}/ --ignore-existing" logoutput="true" checkreturn="true"/>
+    <exec dir="${repo.root}" command="rsync -a --no-g --no-p --update ${blt.root}/template/README.md ${repo.root}/ --ignore-existing" logoutput="true" checkreturn="true"/>
   </target>
 
   <target name="update" depends="init, blt:update-yml, configure">

template/readme/deploy.md docs/deploy.md

@@ -48,6 +48,20 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
   echo "Removing deprecated BLT files from project."
   rm -rf build blt.sh tests/phpunit/blt
 
+  # Removing old docs.
+  rm acsf-setup.md
+  rm architecture.md
+  rm best-practices.md
+  rm deploy.md
+  rm dev-workflow.md
+  rm features-workflow.md
+  rm local-development.md
+  rm onboarding.md
+  rm project-tasks.md
+  rm release-process.md
+  rm repo-architecture.md
+  rm views.md
+
   # Install (new) alias
   echo "Installing blt alias"
   yes | ./vendor/acquia/blt/blt.sh install-alias
@@ -59,7 +73,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/readme/dev-workflow.md docs/dev-workflow.md

@@ -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/examples/readme.md docs/examples/readme.md

@@ -2,22 +2,6 @@
 
 Replace this with a brief description of the ${project.human_name} project.
 
-Documentation by role:
-
-* Developer
-    * [Onboarding](readme/onboarding.md): “how do I get up and running on project work?”
-    * [Repository architecture](readme/repo-architecture.md): “how is the code organized, and why?”
-    * [Running project tasks](readme/project-tasks.md): “how do I _____ on my local machine?”
-    * [Best practices](readme/best-practices.md): "how should I write code?"
-    * [Workflow](readme/dev-workflow.md): “how do I contribute my code to this project?”
-    * [Automated testing](tests/README.md): “how do I write / run them, and why should I care?”
-* Technical Architect
-    * [Project Architecture document](readme/architecture.md)
-    * [Deploying to cloud](readme/deploy.md)
-    * [Release process](readme/release-process.md)
-    * [Setting up continuous integration](readme/ci.md)
-    * [Open source contribution](readme/os-contribution.md)
-
 ## Resources
 
 * JIRA - link me!

docs/extending-blt.md

@@ -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;

template/readme/features-workflow.md docs/features-workflow.md

@@ -39,10 +39,6 @@ public function testBltCreate() {
           '${project.machine_name}',
           file_get_contents($this->newProjectDir . '/docroot/sites/default/settings.php')
       );
-    $this->assertNotContains(
-          '${project.human_name}',
-          file_get_contents($this->newProjectDir . '/readme/architecture.md')
-      );
   }
 
 }