Fixes #1636: Documentation gap for alternative local development envi…

…ronments.

INSTALL.md

@@ -1,6 +1,6 @@
 # BLT installation
 
-*Please do not clone BLT as a means of using it. The only reason to clone BLT is to contribute outside the context of a particular Drupal site.*
+*Please do not clone BLT as a means of using it. The only reason to clone BLT is to contribute to it.
 
 ## System requirements
 
@@ -28,13 +28,13 @@ Then install the  minimum dependencies for BLT. The preferred method is via Home
         brew install php56 git composer drush
         composer global require "hirak/prestissimo:^0.3"
 
-If you'd like to create a VM with BLT, you will require the following additional libraries. If you'd like to use a LAMP stack other than Drupal VM, see [Local Development](readme/local-development.md).
+If you'd like to create a [Drupal VM](https://www.drupalvm.com/) with BLT, you will require the following additional libraries. If you'd like to use a LAMP stack other than Drupal VM, see [Local Development](readme/local-development.md).
 
         brew tap caskroom/cask
         brew cask install virtualbox vagrant
-        vagrant plugin install vagrant-hostsupdater
+        vagrant plugin install vagrant-hostsupdater vagrant-exec
 
-The minimum required versions are VirtualBox 5.1.x and Vagrant 1.8.6. 
+The minimum required versions are VirtualBox 5.1.x and Vagrant 1.8.6.
 
 The local PHP environment should also have a memory limit of at least 2G for BLT to initialize. You can modify your PHP CLI's memory limit by editing php.ini. You can use the following command to open the correct php.ini in TextEdit. Set `memory_limit = 2G`.
 

README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://travis-ci.org/acquia/blt.svg?branch=8.x)](https://travis-ci.org/acquia/blt) [![Documentation Status](https://readthedocs.org/projects/blt/badge/?version=8.x)](http://blt.readthedocs.io/en/8.x/?badge=8.x) [![Packagist](https://img.shields.io/packagist/v/acquia/blt.svg)](https://packagist.org/packages/acquia/blt) [![Stories in Ready](https://badge.waffle.io/acquia/blt.png?label=ready&title=Ready)](http://waffle.io/acquia/blt)
 
-BLT (Build and Launch Tool) is a tool that generates new Drupal projects using a standardized template derived from Acquia Professional Services' best practices.
+BLT (Build and Launch Tool) provides an automation layer for testing, building, and launching Drupal 8 applications.
 
 You can find all BLT documentation on [Read the Docs](http://blt.readthedocs.io):
 
@@ -11,7 +11,7 @@ You can find all BLT documentation on [Read the Docs](http://blt.readthedocs.io)
 
 ## Getting started
 
-See [INSTALL.md](INSTALL.md) for a list of prequisites and links to instructions for [creating new projects](https://github.com/acquia/blt/blob/8.x/readme/creating-new-project.md), [adding BLT to existing projects](https://github.com/acquia/blt/blob/8.x/readme/adding-to-project.md), and [updating BLT](https://github.com/acquia/blt/blob/8.x/readme/updating-blt.md). 
+See [INSTALL.md](INSTALL.md) for a list of prequisites and links to instructions for [creating new projects](https://github.com/acquia/blt/blob/8.x/readme/creating-new-project.md), [adding BLT to existing projects](https://github.com/acquia/blt/blob/8.x/readme/adding-to-project.md), and [updating BLT](https://github.com/acquia/blt/blob/8.x/readme/updating-blt.md).
 
 ## Videos
 
@@ -39,7 +39,7 @@ BLT is designed to improve efficiency and collaboration across Drupal projects b
 Its explicit goals are to:
 
 * Provide a standard project template for Drupal based projects
-* Provide tools that automate much of the setup and maintenance work for projects
+* Provide tools that automate the setup, testing, launching, and maintenance work for projects
 * Document and enforce Drupal standards and best practices via default configuration, automated testing, and continuous integration
 
 Its scope is discretely defined. It is *not* intended to provide:
@@ -50,24 +50,21 @@ Its scope is discretely defined. It is *not* intended to provide:
 
 ## Features
 
-* [Git Hooks](scripts/git-hooks)
+* [Local Git Hooks](scripts/git-hooks)
     * pre-commit: Checks for Drupal coding standards compliance
     * commit-msg: Check for proper formatting and syntax
 * [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](readme/project-tasks.md)
-    * Executing tests and validating code
-    * Building dependencies
-        * Management of Drupal core, contrib, and third party libraries via Composer
-        * Building front end assets. E.g, via gulp, npm, bower, etc.
-    * (Re)installation of Drupal
-      * Configuration import
-* [Artifact Generation](readme/deploy.md)
+* [Commands to automate project tasks](readme/project-tasks.md), like:
+    * Test execution
+    * Frontend asset compilation
+    * Syncing environments
+* [Deployment Artifact Generation](readme/deploy.md)
     * Building production-only dependencies
     * Sanitation of production code
 * [Continuous Integration & Deployment](readme/ci.md)
-    * [Acquia Pipelines](https://dev.acquia.com/request-invite-acquia-pipelines) (coming soon)
+    * [Acquia Pipelines](https://dev.acquia.com/request-invite-acquia-pipelines)
     * [Travis CI](https://travis-ci.com)
     * [GitHub](https://github.com)
 

index.md

@@ -1,4 +1,4 @@
-[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.
+[Acquia BLT (Build and Launch Tool)](https://github.com/acquia/blt) provides an automation layer for testing, building, and launching Drupal 8 applications.
 
 Welcome to the BLT documentation site!
 
@@ -11,7 +11,7 @@ Please read through [Getting started](INSTALL.md) to "install" BLT, then review
 * 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?”
+    * [Running project tasks](readme/project-tasks.md): “how do I [fill-in-the-blank] 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](readme/testing.md): “how do I write / run them, and why should I care?”

readme/ci.md

@@ -8,7 +8,7 @@ Two CI solutions are supported out-of-the-box:
 1. [Travis CI](#travis-ci)
 
 BLT provides one default instruction file (e.g., .travis.yml or acquia-pipelines.yml) for each of these CI solutions, allowing you to have a working build out-of-the-box. To use the default instruction file you must run an initialization command (detailed below). This will copy the default instruction file to the required location, much in the way that Drupal requires you to copy default.settings.php to settings.php.
- 
+
 The instruction files are intended to be customized. BLT will provide updates to the default instruction files, but it is your responsibility to merge those updates into your customized files.
 
 ### Workflow
@@ -39,11 +39,11 @@ To initialize Pipelines support for your BLT project:
         # Move to a location specified in $PATH. E.g.,
         mv pipelines /usr/local/bin
 
-1. [Configure the Pipelines client](https://docs.acquia.com/pipelines/install#authenticate) 
+1. [Configure the Pipelines client](https://docs.acquia.com/pipelines/install#authenticate)
 1. Initialize Pipelines for your project
 
         blt ci:pipelines:init
-   
+
     This will generate an [acquia-pipelines.yml file](https://docs.acquia.com/pipelines/yaml) in your project root based on [BLT's default acquia-pipelines.yml file](https://github.com/acquia/blt/blob/8.x/scripts/pipelines/acquia-pipelines.yml).
 
 1. Commit the new file and push it to your Acquia git remote. Example commands:
@@ -75,7 +75,7 @@ You may [use the Pipelines client](https://docs.acquia.com/pipelines/client) to
     # Show status of all builds.
     pipelines status
     # Find the job-id for to get your Github integrated build logs
-    pipelines list-jobs --application-id=[Application-id] 
+    pipelines list-jobs --application-id=[Application-id]
     # Show logs for most recent Github integrated build.
     pipelines logs --job-ib=[Job-id]
 
@@ -119,7 +119,7 @@ To set up the [workflow described earlier](#workflow), you must configure Acquia
         addons:
           ssh_known_hosts:
           - svn-14671.prod.hosting.acquia.com
-   
+
     Note: if planning on executing any drush sql-syncs/rsyncs between the cloud and your environment, also add the test/stage server host here.
 
 1. Commits or merges to the develop branch on GitHub should now trigger a fully built artifact to be deployed to your specified remotes.
@@ -133,32 +133,8 @@ You can monitor multiple branches on github for deployment, for example master a
 ````
 deploy:
    - provider: script
-     script: blt deploy -Ddeploy.commitMsg="Automated commit by Travis CI for Build ${TRAVIS_BUILD_ID}" -Ddeploy.branch="${TRAVIS_BRANCH}-build"
-     skip_cleanup: true
-     on:
-       branch: master
-
-   - provider: script
-     script: blt deploy -Ddeploy.commitMsg="Automated commit by Travis CI for Build ${TRAVIS_BUILD_ID}" -Ddeploy.branch="${TRAVIS_BRANCH}-build"
+     script: "$BLT_DIR/scripts/travis/deploy_branch"
      skip_cleanup: true
      on:
        branch: integration
 ````
-
-
-#### Automated testing using live content
-
-By default, the Travis CI automated tests install and test your site from scratch. You may also run automated tests against a copy of your production database. This allows you to functionally test update hooks.
-
-Automated testing of live content is easy to set up with two simple steps:
-
-1. Add the hostname of your staging server to .travis.yml:
-
-         ssh_known_hosts:
-           - staging-12345.prod.hosting.acquia.com
-
-2. Follow the steps in [extending BLT](extending-blt.md) to override the default `ci:build:validate:test` target:
-
-         <!-- Override the core ci:build:validate:test target to include a local refresh-->
-         <target name="ci:build:validate:test" description="Builds, validates, tests, and deploys an artifact."
-           depends="validate:all, ci:setup, local:sync, local:update, tests:all" />

readme/creating-new-project.md

@@ -18,10 +18,24 @@
 
     By default, BLT will use the [`lightning`](https://github.com/acquia/lightning) profile, other valid values are `standard` or `minimal`.
 
-1. If using Drupal VM for local development, run the following commands. Otherwise, see [Local Development](http://blt.readthedocs.io/en/8.x/readme/local-development/).
+1. Now its time to spin up your LAMP stack.
+  - **With Drupal VM**: If you would like to use Drupal VM for local development, run the following commands.
 
         blt vm
-        blt local:setup
+
+
+  - **Without Drupal VM**: If you would not like to use Drupal VM, please review [Local Development](http://blt.readthedocs.io/en/8.x/readme/local-development/) and set up your own LAMP stack. Once your LAMP stack is running, execute the following command to generate default local settings files:
+
+        blt setup:settings
+
+    Modify the generated `docroot/sites/default/settings/local.settings.php` file by adding your custom MySql credentials.
+
+1. Execute the following command to complete setup:
+
+        blt setup
+
+   This will generate all required files and install Drupal.
 
 1. Login to Drupal `drush @[project.machine_name].local uli`, where [project.machine_name] is the value that you set in project.yml.
+
 1. See [Next steps](next-steps.md).

readme/deploy.md

@@ -37,10 +37,16 @@ After the artifact is created, you can inspect it or even run it as a website lo
 
 To both create and deploy the build artifact in a single command, run the following command
 
-    blt deploy -Ddeploy.branch=develop-build -Ddeploy.commitMsg='BLT-123: The commit message.'
+    blt deploy --commit-msg "BLT-000: Example deploy to branch" --branch "develop-build" --no-interaction
 
 This command will commit the artifact to the `develop-build` branch with the specified commit message and push it to the remotes defined in project.yml.
 
+To create a new git tag for the artifact (rather than committing to a branch) run:
+
+    blt blt deploy --commit-msg "Creating release 1.0.0." --tag "1.0.0"
+
+This will generate the artifact, tag it with `1.0.0`, and push it to the remotes defined in project.yml.
+
 ## Modifying the artifact
 
 The artifact is built by running the `deploy:build` target, which does the following:
@@ -56,7 +62,7 @@ See [Extending BLT](extending-blt.md) for more information on overriding default
 
 If you would like to create, commit, but _not push_ the artifact, you may do a dry run:
 
-    blt deploy -Ddeploy.branch=develop-build -Ddeploy.commitMsg='BLT-123: The commit message.' -Ddeploy.dryRun=true
+    blt deploy -D deploy.dryRun=true
 
 This is helpful for debugging deployment artifacts.
 

readme/extending-blt.md

@@ -8,24 +8,26 @@ To create your own Robo PHP command:
 
 1. Create a new file in `blt/src/Commands` named using the pattern `*Command.php`. The file naming convention is required.
 1. You must use the namespace `Acquia\Blt\Custom\Commands` in your command file.
+1. Generate an example command file by executing `blt example:init`. You may use the generated file as a guide for writing your own command.
 1. Follow the [Robo PHP Getting Started guide](http://robo.li/getting-started/#commands) to write a custom command.
 
-For an example implementation, please see [ExampleCommand.php](../template/blt/src/Commands/ExampleCommand.php).
-
 ## Adding a custom Robo Hook
 
 BLT uses the [Annotated Command](https://github.com/consolidation/annotated-command) library to enable you to hook into BLT commands. This allows you to execute custom code
 in response to various events, typically just before or just after a BLT command is executed.
 
-To create a hook, create a new file in `blt/src/Hooks` named using the pattern `*Hook.php`.
+To create a hook:
 
-For an example implementation, please see [ExampleHook.php](../template/blt/src/Hooks/ExampleHook.php).
+1. Create a new file in `blt/src/Hooks` named using the pattern `*Hook.php`.
+1. Generate an example hook file by executing `blt example:init`. You may use the generated file as a guide for writing your own command.
 
 For a list of all available hook types, see [Annotated Command's hook types](https://github.com/consolidation/annotated-command#hooks).
 
 ## Replacing/Overriding a Robo Command
 
-@todo Document this!
+To replace a BLT command with your own custom version, implement the [replace command annotation](https://github.com/consolidation/annotated-command#replace-command-hook) for your custom command.
+
+Please note that when you do this, you take responsibility for maintaining your custom command. Your command may break when changes are made to the upstream version of the command in BLT itself.
 
 ## Overriding a variable value:
 
@@ -51,7 +53,18 @@ This snippet would cause the `validate:phpcs` target to be skipped during BLT bu
 
 ## Adding / overriding filesets
 
-@todo Document this!
+1. Generate an example `Filesets.php` file by executing `blt example:init`. You may use the generated file as a guide for writing your own filesite.
+1. Create a public method in the `Filesets` class in the generated file.
+1. Add a Fileset annotation to your public method, specifying its id:
+
+        @fileset(id="files.php.custom.mytheme")
+
+1. Instantiate and return a `Symfony\Component\Finder\Finder` object. The files found by the finder comprise the fileset.
+1. You may use the Fileset id in various configuration values in your `blt/project.yml` file. E.g., modify `validate:phpcs` such that it scans only your custom fileset, you would add the following to `blt/project.yml`:
+
+        phpcs:
+          filesets:
+            - files.php.custom.mytheme
 
 ## Modifying BLT Configuration
 
@@ -126,19 +139,11 @@ To modify the behavior of the tests:behat target, you may override BLT's `behat`
 
         behat:
           config: ${repo.root}/tests/behat/local.yml
-          haltonerror: true
-          strict: true
           profile: local
-          # If true, `drush runserver` will be used for executing tests.
-          run-server: false
           # The URL of selenium server. Must correspond with setting in behat's yaml config.
           selenium:
             port: 4444
             url: http://127.0.0.1:${behat.selenium.port}/wd/hub
-          # This is used for ad-hoc creation of a server via `drush runserver`.
-          server:
-            port: 8888
-            url: http://127.0.0.1:${tests.server.port}
           # An array of paths with behat tests that should be executed.
           paths:
             # - ${docroot}/modules

readme/local-development.md

@@ -4,7 +4,8 @@
 Acquia currently recommends the use of either:
 
   * [Drupal VM](#using-drupal-vm-for-blt-generated-projects): An isolated virtual machine, built with Vagrant and Ansible.
-  * [Acquia Dev Desktop](#acquia-dev-desktop): A turn-key LAMP stack tailored specifically for Acquia-hosted Drupal sites.
+  * [Acquia Dev Desktop](#using-acquia-dev-desktop-for-blt-generated-projects): A turn-key LAMP stack tailored specifically for Acquia-hosted Drupal sites.
+  * [Alternative local development environments](http://blt.readthedocs.io/en/8.x/readme/local-development/#alternative-local-development-environments)
 
 No matter what local environment you choose to use, the following guidelines should be followed:
 

readme/next-steps.md

@@ -39,7 +39,6 @@ Other commonly used commands:
         blt tests:phpunit
 
         # ssh into vm & run behat tests
-        drush @[project.machine_name].local ssh
         blt tests:behat
 
         # diagnose issues

readme/onboarding.md

@@ -2,14 +2,6 @@
 
 Here is a quick-start guide to getting your local development environment set up and getting oriented with the project standards and workflows.
 
-## Required SAAS Access:
-
-Please ask the project's engagement manager for access to the following SaaS services:
-
-* JIRA
-* GitHub repository
-* Acquia Cloud subscription
-
 ## System Requirements
 
 Verify that your system meets [System requirements](../INSTALL.md)

readme/updating-blt.md

@@ -7,13 +7,16 @@ If you are already using BLT via Composer, you can update to the latest version
 1. To update to the latest version of BLT that is compatible with your existing dependencies, run the following commands:
 
         composer update acquia/blt --with-dependencies
-  
+
 1. Sometimes, the first command will fail to update to the latest version of BLT. This is typically because some other dependency prevents it. If this happens, run:
-
-        composer require acquia/blt:^[latest-version] --no-update && composer update
-         
-   Where `[latest-version]` is the latest version of BLT. E.g., `8.7.0`. This will cause Composer to update all of your dependencies (in accordance with your version constraints) and permit the latest version of BLT to be installed.
-1. Check the [release information](https://github.com/acquia/blt/releases) to see if there are special update instructions for the new version. 
+
+        rm -rf vendor && composer require acquia/blt:^[latest-version] --no-update && composer update
+
+   Where `[latest-version]` is the latest version of BLT. E.g., `8.7.0`.
+
+   This will cause Composer to update all of your dependencies (in accordance with your version constraints) and permit the latest version of BLT to be installed.
+
+1. Check the [release information](https://github.com/acquia/blt/releases) to see if there are special update instructions for the new version.
 1. Review and commit changes to your project files.
 1. Rarely, you may need to refresh your local environment via `blt local:setup`. This will drop your local database and re-install Drupal.
 

src/Robo/Commands/Vm/VmCommand.php

@@ -113,7 +113,7 @@ protected function install() {
   /**
    * Generates default configuration for Drupal VM.
    *
-   * @command vm:config
+     * @command vm:config
    */
   public function config() {