Converting BLT to composer package. (#217)

* Moving template/build to build.

* Removing custom tasks dir.

* Removing build/core.

* Removing template dir.

* Fixing incorrect paths in phpunit tests.

* Fixing executables.

* Removing unnecessary git fetch.

* Making phpcs filesets configurable.

* Working on upgrade path.

* Updating install docs and process.

* Making setup tasks more verbose.

* Using fork of composer-patches.

* Adding update instructions.

* More improvements to verbosity.

* debug

* Fixing rsync issues.

* updating instructions.

* fixing upgrade script.

* fixing travis.

* Adding create-project target.

* Adding blt-project instructions.

* Installing alias as part of init.

* fixing travis

* more docs fixes.

* Replace blt sh mentions with blt alias. (#263)

* Allowing custom import.

* Removing changes from rebase.

.gitignore

@@ -2,9 +2,6 @@
 /project.yml
 local.*
 
-# Ignore build artifacts
-bin/*
-
 # OS X
 .DS_Store
 .AppleDouble

.travis.yml

@@ -4,6 +4,7 @@ language: php
 
 php:
   - 5.6
+  - 7
 
 cache:
   bundler: true
@@ -25,9 +26,8 @@ addons:
 before_install:
   # Decrypt private SSH key id_rsa_blt.enc, save as ~/.ssh/id_rsa_blt.
   - if [[ "$TRAVIS_PULL_REQUEST" == "false" ]]; then openssl aes-256-cbc -K $encrypted_c0b166e924da_key -iv $encrypted_c0b166e924da_iv -in id_rsa_blt.enc -out ~/.ssh/id_rsa -d; chmod 600 ~/.ssh/id_rsa; ls -lash ~/.ssh; eval "$(ssh-agent -s)"; ssh-add ~/.ssh/id_rsa; fi
-  - nvm install 0.12
-  - nvm use 0.12
   - composer selfupdate
+  # Disable xdebug.
   - phpenv config-rm xdebug.ini
   # Enable $_ENV variables in PHP.
   - echo 'variables_order = "EGPCS"' >> ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/travis.ini
@@ -38,10 +38,16 @@ before_install:
   - mysql -e 'CREATE DATABASE drupal;'
 
 install:
+  # Load composer dependencies.
   - composer validate --no-check-all --ansi
+  # Remove acquia packages from cache before running `composer install`.
+  - rm -rf vendor/acquia
   - composer install
   - export PATH=$TRAVIS_BUILD_DIR/vendor/bin:$PATH
-  # Initialize drupal consile default configuration.
+  # 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:
@@ -53,27 +59,36 @@ before_script:
 script:
   # Ensure code quality of 'blt' itself.
   - phpcs --standard=./vendor/drupal/coder/coder_sniffer/Drupal/ruleset.xml tests
-  # Generate a new 'blted' project.
-  - ./blt.sh configure
+  # Generate a new 'blt-project' project.
+  - cp -R blt-project ../
+  - cd ../blt-project
+  - git init
+  - git add -A
+  # Commit so that susbsequent git commit tests have something to ammend.
+  - git commit -m 'Initial commit.'
+  # BLT is the only dependency at this point. Install it.
+  - composer install
+  - export PATH=$TRAVIS_BUILD_DIR/../blt-project/vendor/bin:$PATH
+  - yes | blt init
   # The local.hostname must be set to 127.0.0.1:8888 because we are using drush runserver to run the site on Travis CI.
   - drupal yaml:update:value project.yml project.local.hostname '127.0.0.1:8888'
-  - ./blt.sh create
-  # Move to the target directory.
-  - cd ../blted8
-  # Call targets in the new 'blted' project.
-  - ./blt.sh ci:build:validate:test -Dcreate_alias=false -Dbehat.run-server=true -Dbehat.launch-phantom=true
+  - blt configure
+  # Running `blt init` modified composer.json, so we must update.
+  - composer update
+  # Call targets in the new 'blt-project' project.
+  - blt ci:build:validate:test -Dcreate_alias=false -Dbehat.run-server=true -Dbehat.launch-phantom=true
   # Deploy build artifact.
-  - ./blt.sh deploy:build -Ddeploy.commitMsg="Automated commit by Travis CI for Build ${TRAVIS_BUILD_ID}" -Ddeploy.branch="8.x-build"
+  - blt deploy:build
   # Add Drupal VM config to repo.
-  - ./blt.sh vm:init
-  # Switch back to 'blt' directory
+  - blt vm:init
+  # Switch back to 'blt' directory.
   - cd ../blt
   # Run 'blt' phpunit tests, excluding deploy-push tests.
   - phpunit tests/phpunit --exclude-group deploy-push
 
 deploy:
   provider: script
-  script: ../blted8/blt.sh deploy -Ddeploy.commitMsg="Automated commit by Travis CI for Build ${TRAVIS_BUILD_ID}" -Ddeploy.branch="8.x-build" && phpunit tests/phpunit --group=deploy
+  script: cd blt-project && blt deploy -Ddeploy.commitMsg="Automated commit by Travis CI for Build ${TRAVIS_BUILD_ID}" -Ddeploy.branch="8.x-build" && phpunit tests/phpunit --group=deploy
   skip_cleanup: true
   on:
     branch: 8.x

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to BLT
+
+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:
+
+* 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.
+* Feature that are part of the [Road Map](https://github.com/acquia/blt/wiki/Road-Map)
+  will be prioritized for inclusion.
+
+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).
+
+## Developing BLT locally
+
+If you'd like to contribute by actively developing BLT, we suggest that you clone BLT and also created a BLT-ed project for testing your changes.
+
+Use the following commands to create a testable BLT-created project alongside BLT
+
+```
+git clone https://github.com/acquia/blt.git
+cp -R blt/blt-project .
+cd blt-project
+composer install
+./vendor/acquia/blt/blt.sh install-alias
+blt init
+blt configure
+composer update
+```
+
+The new `blt-project` directory will have a composer dependency on your local clone of BLT via a `../blt` symlink. You can therefore make changes to files in `blt` and see them immediately reflected in `blt-project/vendor/acquia/blt`.
+
+## Development conventions
+
+### Phing targets vs. Symfony commands?
+
+While Phing and the Symfony Console can both accomplish some of the same tasks, they are different tools with different intended purposes. When developing functionality for BLT we are careful to choose the right tool for the right job.
+
+Phing is intended to be build tool. It is particularly good at stringing together multiple commands and tasks into a single target which can then be executed procedurally. We use Phing when are requirements are well suited to this strength.
+
+The commands that Phing executes can, of course, be provided by anything. Some are native linux commands, some are provided by tools like Composer and NPM, while others may be provided by the Symfony Console component.
+
+As a rule, we _use Symfony console to provide fixed-scope commands_. These commands should be flexible and have absolutely no intrinsic awareness of the greater build process. We _use Phing to call commands within the context of a build process_, executing them with specific argument values at the correct time.
+

INSTALL.md

@@ -1,62 +1,121 @@
-## Creating a new project with BLT
+# BLT installation and updates
 
-The following high-level steps will be required to generate a new, fully functioning site using BLT:
-
-1. Ensure your native OS meets minimum requirements
-1. Clone BLT to your local machine
-1. Generate and modify configuration files for your new project
-1. Use BLT’s “installer” to generate a new site
-1. Setup a local *AMP stack
-1. Build your new project’s dependencies and install locally
+* System requirements
+* [Creating a new project with BLT](#creating-new)
+* [Adding BLT to an existing project](#existing-project)
+* [Updating to the latest version of BLT](#updating)
+  * [Updating from a non-composer-managed version](#update-non-composered)
+  * [Updating a composer-managed version](#update-composered)
 
 ## System Requirements
 
 You should be able to use the following tools on the command line of your native operating system:
 
 * [Git](https://git-scm.com/)
 * [Composer](https://getcomposer.org/download/)
-* PHP 5.6. PHP installation instructions:
+* PHP 5.6+, PHP installation instructions:
     * [OSX](http://justinhileman.info/article/reinstalling-php-on-mac-os-x/)
     * [Windows](http://php.net/manual/en/install.windows.php)
     * [Linux](http://php.net/manual/en/install.unix.debian.php)
-
-## Prepare BLT installer
-
-* Clone BLT to your local machine on your native OS:
-  `git clone https://github.com/acquia/blt.git` 
-
-# Generate and modify configuration files
-
-From the BLT repository’s root directory, run `./blt.sh configure`. This will create your project-specific configuration files. After running, the following files should exist in the BLT root directory:
-
-* project.yml
-* local.settings.php
-
-You will need to open these files and modify their values with settings for your project. At a minimum, you must set the following configuration items:
-
-* Local site DB credentials: `$databases` in local.settings.php
-
-At this point, you likely have not configured your local *AMP stack for your new site. That’s ok. Simply enter the local URL and local DB credentials that you intend to use when your *AMP stack is up and running.
-
-## Create a new project
-
-BLT’s “installer” will do the following:
-* Create new project directory (sibling of the BLT repository)
-* Copies BLT template files to the new directory
-* Replaces tokens in copied files with project-specific strings
-* Removes installation artifacts
-
-Run `./blt.sh create` to do all the things!
-
-Once it’s completed, __change directories to your new project directory. All subsequent steps will happen inside your new project. You have left the BLT repository behind.__
-
-## Modifying project files
-
-This is an optional step. Important files that you may want to modify include:
-
-* composer.json. Note that Drupal core, contrib, and third party dependencies are all managed here.
-* Project’s root README.md.
-* Other project documentation in the readme directory.
+* [NPM](https://nodejs.org/en/download/) (for [Lightning](https://github.com/acquia/lightning) support)
+
+### Recommended tools and configuration
+
+* Globally install pretissimo for parallelized composer downloads:
+
+  ```
+  composer global require "hirak/prestissimo:^0.3"
+  ```
+* If you have xDebug enabled for your PHP CLI binary, it is highly recommended that you disable it to dramatically improve performance.
+
+## <a name="creating-new"></a>Creating a new project with BLT
+
+1. Create a new project using the [blt-project](https://github.com/acquia/blt-project) template:
+
+  ```
+  composer create-project acquia/blt-project:8.x-dev MY_PROJECT --no-interaction
+  cd MY_PROJECT
+  ```
+1. Install the `blt` alias and follow on-screen instructions:
+
+  ```
+  ./vendor/bin/blt install-alias
+  ```
+1. Customize BLT configuration files:
+  * `project.yml`
+  * `docroot/sites/default/settings/local.settings.php`
+    * Add your local DB credentials to `$databases`
+1. Replace tokens in new BLT-generated files with your custom values in project.yml:
+
+  ```
+  blt configure
+  ```
+1. (optional) Modify project files. Important files that you may want to modify include:
+  * composer.json. Note that Drupal core, contrib, and third party dependencies are all managed here.
+  * Project’s root README.md.
+  * Other project documentation in the readme directory.
+1. (optional) Follow instructions for <a href="#install">installing Drupal locally</a>.
+
+## <a name="existing-project"></a>Adding BLT to an existing project
+
+To add BLT to a pre-existing Drupal project, do the following:
+
+1. Ensure that your project directory structure is Acquia-cloud compatible by asserting that the Drupal root is in a top-level folder called `docroot`.
+1. If you currently manage your dependencies via Composer, ensure that they are all up to date via `composer update`. Assert that these updates do not break your project.
+1. `cd` into your existing project directory.
+1. Add BLT via composer and initialize it:
+  ```
+  composer require acquia/blt:~8
+  ./vendor/acquia/blt/blt.sh init
+  ```
+1. (optional) Modify project files. Important files that you may want to modify include:
+  * composer.json. Note that Drupal core, contrib, and third party dependencies are all managed here.
+  * Project’s root README.md.
+  * Other project documentation in the readme directory.
+1. (optional) Follow instructions for <a href="#install">installing Drupal locally</a>.
+
+## <a name=""></a>Updating BLT
+
+### <a name=""></a>Updating a composer-managed version
+
+If you are already using BLT via Composer, you can update to the latest version of BLT by running the following commands from your project's root directory:
+
+```
+composer update acquia/blt
+blt update
+```
+
+### <a name=""></a>Updating from a non-Composer-managed version
+
+If you are using an older version of BLT that was not installed using Composer, you may update to the Composer-managed version by running the following commands:
+
+1. Remove any dependencies that may conflict with upstream acquia/blt. You may add these back later after the upgrade, if necessary.
+
+  ```
+  composer remove drush/drush drupal/console phing/phing phpunit/phpunit squizlabs/php_codesniffer symfony/yaml drupal/coder symfony/console --no-interaction --no-update
+  composer remove drush/drush drupal/console phing/phing phpunit/phpunit squizlabs/php_codesniffer symfony/yaml drupal/coder symfony/console --dev --no-interaction --no-update
+  composer config minimum-stability dev
+  ```
+1. (conditional) If you are using Lightning, verify that your version constraint allows it to be updated to the latest stable version:
+
+  ```
+  composer require drupal/lightning:~8 --no-update
+  ```
+1. Require acquia/blt as a dev dependency:
+
+  ```
+  composer require acquia/blt:~8 --dev --no-update
+  ```
+1. Update all dependencies:
+
+  ```
+  composer update
+  ```
+1. Execute update script:
+
+  ```
+  ./vendor/acquia/blt/scripts/blt/convert-to-composer.sh
+  ```
 
 Note that all of the steps from this point forward are the same steps that would be used by a newly onboarded developer setting up your existing project on their local machine for the first time.
 
@@ -65,7 +124,7 @@ 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:
-  * [Acquia Dev Desktop](template/readme/local-development.md#using-acquia-dev-desktop-for-blt-generated-projects)  
+  * [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)
 
@@ -74,9 +133,9 @@ When you have completed setting up your local \*AMP stack, double check that the
 * Local site DB credentials: `$databases` in docroot/sites/default/settings/local.settings.php
 * Local site URL: `$options[‘uri’]` in docroot/sites/default/local.drushrc.php
 
-## Build your project’s dependencies and install Drupal
+## <a name="install"></a>Build your project’s local dependencies and install Drupal locally
 
-Run the following command from the project root: `./blt.sh local:setup`. This will do a lot of things for you, including:
+Run the following command from the project root: `blt local:setup`. This will do a lot of things for you, including:
 
 * Building dependencies
 * Installing local git hooks
@@ -85,13 +144,8 @@ Run the following command from the project root: `./blt.sh local:setup`. This wi
 
 When this task is complete, you should have a fully functioning Drupal site on your local machine. You can login to the site by running `drush uli`.
 
-Note that all common project tasks are executed through `blt.sh` in your project’s root directory. This file simply passes arguments through to Phing, which manages all task automation. For a full list of available tasks, run `./blt.sh -l`.
+Note that all common project tasks are executed through `blt`. For a full list of available tasks, run `blt -l`.
 
 ## Next Steps
 
-Now that your new project works locally, you’ll want to integrate with with your SAAS tools (GitHub, TravisCI, Jenkins, etc.) and your Acquia Cloud subscription.
-
-See the following documents for more detailed instructions on those tasks:
-
-* Configure your CI solution @todo link
-* Deploy to Acquia Cloud @todo link
+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.