Add build-env:create-project command

README.md

@@ -1,10 +1,11 @@
 # Terminus Build Tools Plugin
 
+[![CircleCI](https://circleci.com/gh/pantheon-systems/terminus-build-tools-plugin.svg?style=svg)](https://circleci.com/gh/pantheon-systems/terminus-build-tools-plugin)
 [![Terminus v1.x Compatible](https://img.shields.io/badge/terminus-v1.x-green.svg)](https://github.com/pantheon-systems/terminus-build-tools-plugin/tree/1.x)
 
-Terminus Plugin that contain a collection of commands useful during the build step on a [Pantheon](https://www.pantheon.io) site that uses a GitHub PR workflow.
+Terminus Plugin that contain a collection of commands useful during the build step on a [Pantheon](https://www.pantheon.io) site that manages its files using Composer, and uses a GitHub PR workflow with Behat tests run via Circle CI (or some other testing service).
 
-An [example circle.yml file](example.circle.yml) has been provided to show how this tool should be used with CircleCI. When a test runs against a "light" repository on GitHub, the following things will happen:
+An [example circle.yml file](example.circle.yml) has been provided to show how this tool should be used with CircleCI. When a test runs against a "canonical" repository on GitHub, the following things will happen:
 
 - Git is configured for making clones and commits.
 - Terminus 1.x is installed.
@@ -21,13 +22,69 @@ See below for the list of supported commands. This plugin is only available for
 
 ## Configuration
 
-In order to use this plugin, you will need to set up a GitHub repository and a CircleCI project for the site you wish to build. Credentials will also need to be set up (to be documented).
+In order to use this plugin, you will need to set up a GitHub repository and a CircleCI project for the site you wish to build. Credentials also need to be set up.
+
+### Credentials
+
+In order to use the build-env:create-project command, the first thing that you need to do is set up credentials to access GitHub and Circle CI. Instructions on creating these credentials can be found on the pages listed below:
+
+- GitHub: https://help.github.com/articles/creating-an-access-token-for-command-line-use/
+- Circle CI: https://circleci.com/docs/api/#authentication
+
+These credentials may be exported as environment variables. For example:
+```
+#!/bin/bash
+export GITHUB_TOKEN=[REDACTED]
+export CIRCLE_TOKEN=[REDACTED]
+```
+If you do not export these environment variables, you will be prompted to enter them when you run the build-env:create-project command.
+
+### Create a New Project Quickstart
+
+EXPERIMENTAL: The build-env:create-project is under development. Backwards compatibility not guarenteed until version 1.3.0.
+
+To create a new project consisting of a GitHub project, a Pantheon site, and Circle CI tests, first set up credentials as shown in the previous section, and then run the `build-env:create-project` command as shown below:
+```
+terminus build-env:create-project --team="Agency Org Name" d8 example-site
+```
+
+This single command will:
+
+- Create a new GitHub repository named `example-site`, cloned from the started site repository.
+- Create a new Pantheon site built from the GitHub repository.
+- Configure CircleCI to run Behat tests on the site on every pull request.
+- Configure credentials on all of these services to allow the test scripts to run.
+
+Note that it is important to specify the name of your agency organization via the `--team` option. If you do not do this, then your new site will not have the capability to create multidev environments. In this instance, all of your tests will run on the dev environment. See [Running Tests without Multidevs](#running-tests-without-multidevs), below, for more information.
+
+In the example above, the parameter `d8` is shorthand for the project `pantheon-systems/example-drops-8-composer`, the canonical Composer-managed Drupal 8 site for Pantheon. You may replace this parameter with the GitHub organization and project name for any other canonical starter site that you would like to use.
+
+| Starter Site | Shorthand | Packagist Project Name                    |
+| ------------ | --------- | ----------------------------------------- |
+| Drupal 8     | d8        | [pantheon-systems/example-drops-8-composer](https://github.com/pantheon-systems/example-drops-8-composer) |
+| Drupal 7     | d7        | [pantheon-systems/example-drops-7-composer](https://github.com/pantheon-systems/example-drops-7-composer) |
+
+More starter sites will be available in the future. You may easily create your own by following the example of the existing starter site, and publishing your customized version on Packagist. At the moment, there is no way to extend the list of shorthand site names, though.
+
+Additional options are available to further customize the build-env:create-project command:
+
+| Option           | Description    |
+| ---------------- | -------------- |
+| --pantheon-site  | The name to use for the Pantheon site (defaults to the name of the GitHub site) | 
+| --team           | The Pantheon team to associate the site with |
+| --org            | The GitHub org to place the repository in (defaults to authenticated user) |
+| --email          | The git user email address to use when committing build results |
+| --test-site-name | The name to use when installing the test site |
+| --admin-password | The password to use for the admin when installing the test site |
+| --admin-email    | The email address to sue for the admin |
+
+See `terminus help build-env:create-project` for more information.
 
 ### Build Customizations
 
 To customize this for a specific project:
 
-- Define necessary environment variables in the Circle project settings:
+- Define necessary environment variables in the Circle project settings file `circle.yml`:
   - TERMINUS_SITE: The name of the Pantheon site that will be used in testing.
   - TERMINUS_TOKEN: A Terminus OAuth token that has write access to the terminus site specified by TERMINUS_SITE.
   - GIT_EMAIL: Used to configure the git user’s email address for commits we make.
@@ -37,31 +94,35 @@ To customize this for a specific project:
 - [Add a `build-assets` script](https://pantheon.io/blog/writing-composer-scripts) to your composer.json file.
 - Add any needed cleanup steps (e.g. `drush updatedb`) after `build-env:merge`.
 
-### Specific Examples
-
-For a more specific example, see:
-
-- https://github.com/pantheon-systems/example-drops-8-composer
-
 ### PR Environments vs Other Test Environments
 
 Note that using a single environment for each PR means that it is not possible to run multiple tests against the same PR at the same time. Currently, no effort is made to cancel running tests when a new one is kicked off; if the concurrent build is not cancelled before a new commit is pushed to the PR branch, then the two tests could potentially conflict with each other. If support for parallel tests on the same PR is desired, then it is possible to eliminate PR environments, and make all tests run in their own independent CI environment. To do this, make the following change in the environments section of the circle.yml file:
-
+```
     TERMINUS_ENV: $CI_LABEL
-
+```
 ### Running Tests without Multidevs
 
 To use this tool on a Pantheon site that does not have multidev environments support, it is possible to run all tests against the dev environment. If this is done, then clearly it is not possible to run multiple tests at the same time. To use the dev environment, make the following change in the environments section of the circle.yml file:
-
+```
     TERMINUS_ENV: dev
+```
+** IMPORTANT NOTE: ** If you initially set up your site using `terminus build-env:create-project`, and you do **not** use the `--team` option, or the team you specify is not an Agency organization, then your Circle configuration will automatically be set up to use only the dev environment. If you later add multidev capabilities to your site, you will need to [visit the Circle CI environment variables configuration page](https://circleci.com/docs/api/#authentication) and **delete** the entry for TERMINUS_ENV.
 
 ## Examples
 
+The examples below show how some of the other build-env commands are used within test scripts. It is not usually necessary to run any of these commands directly.
+
 ### Create Testing Multidev
 
 `terminus build-env:create my-pantheon-site.dev ci-1234`
 
-This command will commit the generated artifacts to a new branch and then create the requested multidev environment for use in testing. Note that it is very important that the .gitignore file allow the build artifacts to be added to the  repository. If the build artifacts are normally included in the .gitignore file (e.g. to keep them from being added to the GitHub repository), then the .gitignore file should be modified during the build step to remove any entry that excludes artifacts. Modifications to the .gitignore file will *not* be included in the commit, so the resulting multidev environment will ignore any changes made to the build artifacts when making commits on the Pantheon site during on-server development.
+This command will commit the generated artifacts to a new branch and then create the requested multidev environment for use in testing.
+
+### Push Code to an Existing Multidev
+
+`terminus build-env:push-code my-pantheon-site.dev`
+
+This command will commit the generated artifacts to an existing multidev environment, or to the dev environment.
 
 ### Merge Testing Multidev into Dev Environment
 

circle.yml

@@ -0,0 +1,58 @@
+#
+# IMPORTANT NOTE:
+#
+# This is the test script for the Terminus Build Tools Plugin itself.
+# You probably DO NOT want to use this as a template to emulate for setting
+# up tests for other Terminus plugins or Pantheon sites.
+#
+# This test suite creates an entire Pantheon site (and corresponding
+# Github project and Circle CI configuration) for EVERY SINGLE TEST. For
+# most other projects, you will want to create your test environment once,
+# and re-use it for every test.
+#
+# See `example.circle.yml` for a more reasonable boilerplate.
+#
+machine:
+  timezone:
+    America/Chicago
+  php:
+    version: 7.0.11
+  environment:
+    TERMINUS_SITE: build-tools-$CIRCLE_BUILD_NUM
+    TERMINUS_ORG: CI for Drupal 8 + Composer
+    GITHUB_USERNAME: pantheon-ci-bot
+    SOURCE_COMPOSER_PROJECT: pantheon-systems/example-drops-8-composer
+    TARGET_REPO: $GITHUB_USERNAME/$TERMINUS_SITE
+    TARGET_REPO_WORKING_COPY: $HOME/$TERMINUS_SITE
+    PATH: $PATH:~/.composer/vendor/bin:~/.config/composer/vendor/bin
+
+dependencies:
+  cache_directories:
+    - ~/.composer/cache
+  pre:
+    - git config --global user.email "$GIT_EMAIL"
+    - git config --global user.name "Circle CI"
+  override:
+    - gem install circle-cli
+    - composer global require -n "hirak/prestissimo:^0.3"
+    - composer global require -n "consolidation/cgr"
+    - cgr "pantheon-systems/terminus:~1" --stability beta
+    - terminus --version
+    # Link the project directory as a Terminus plugin.
+    - mkdir -p $HOME/.terminus/plugins
+    - ln -s $(pwd) $HOME/.terminus/plugins
+    - terminus list -n build-env
+  post:
+    - terminus auth:login -n --machine-token="$TERMINUS_TOKEN"
+test:
+  override:
+    - terminus build-env:create-project -n "$SOURCE_COMPOSER_PROJECT" "$TERMINUS_SITE" --team="$TERMINUS_ORG" --email="$GIT_EMAIL"
+    # Confirm that the Pantheon site was created
+    - terminus site:info "$TERMINUS_SITE"
+    # Confirm that the Github project was created
+    - git clone "https://github.com/${TARGET_REPO}.git" "$TARGET_REPO_WORKING_COPY"
+    # Confirm that Circle was configured for testing, and that the first test passed
+    - cd "$TARGET_REPO_WORKING_COPY" && circle token "$CIRCLE_TOKEN" && circle watch
+  post:
+    # Delete the Pantheon site, the Github project, and the Circle configuration
+    - terminus build-env:obliterate -n "$TERMINUS_SITE"

example.circle.yml

@@ -1,29 +1,40 @@
 # Generic circle.yml for using the Terminus Build Tools Plugin to
 # test a Pantheon site. See the README for customization instructions.
 
-# https://circleci.com/docs/configuration#machine
 machine:
   timezone:
     America/Chicago
   php:
-    # https://circleci.com/docs/build-image-trusty/#php
     version: 7.0.11
   environment:
-    TERMINUS_SITE: my-test-site
+    # In addition to the environment variables defined in this file, also
+    # add the following variables in the Circle CI UI.
+    #
+    # See: https://circleci.com/docs/1.0/environment-variables/
+    #
+    # TERMINUS_SITE:  Name of the Pantheon site to run tests on, e.g. my_site
+    # TERMINUS_TOKEN: The Pantheon machine token
+    # GITHUB_TOKEN:   The GitHub personal access token
+    # GIT_EMAIL:      The email address to use when making commits
+    #
+    # TEST_SITE_NAME: The name of the test site to provide when installing.
+    # ADMIN_PASSWORD: The admin password to use when installing.
+    # ADMIN_EMAIL:    The email address to give the admin when installing.
+    #
+    # The variables below usually do not need to be modified.
     BRANCH: $(echo $CIRCLE_BRANCH | grep -v '^\(master\|[0-9]\+.x\)$')
-    PR_LABEL: ${BRANCH:+pr-$BRANCH}
-    CI_LABEL: ci-$CIRCLE_BUILD_NUM
-    TERMINUS_ENV: $(echo ${PR_LABEL:-$CI_LABEL} | cut -c -11 | sed 's/-$//')
-    TERMINUS_ENV_LABEL: CI-$CIRCLE_BUILD_NUM
-    PATH: $PATH:~/.composer/vendor/bin:~/.config/composer/vendor/bin
+    PR_ENV: ${BRANCH:+pr-$BRANCH}
+    CIRCLE_ENV: ci-$CIRCLE_BUILD_NUM
+    DEFAULT_ENV: $(echo ${PR_ENV:-$CIRCLE_ENV} | cut -c -11 | sed 's/-$//')
+    TERMINUS_ENV: ${TERMINUS_ENV:-$DEFAULT_ENV}
+    NOTIFY: 'scripts/github/add-commit-comment {project} {sha} "Created multidev environment [{site}#{env}]({dashboard-url})." {site-url}'
+    PATH: $PATH:~/.composer/vendor/bin:~/.config/composer/vendor/bin:tests/scripts
 
 dependencies:
   cache_directories:
     - ~/.composer/cache
   pre:
-    - echo "Begin build for $CI_LABEL${PR_LABEL:+ for }$PR_LABEL. Pantheon test environment is $TERMINUS_SITE.$TERMINUS_ENV"
-    # Avoid ssh prompting when connecting to new ssh hosts
-    - echo "StrictHostKeyChecking no" >> "$HOME/.ssh/config"
+    - echo "Begin build for $CIRCLE_ENV${PR_ENV:+ for }$PR_ENV. Pantheon test environment is $TERMINUS_SITE.$TERMINUS_ENV"
     - |
       if [ -n "$GITHUB_TOKEN" ] ; then
         composer config --global github-oauth.github.com $GITHUB_TOKEN
@@ -33,11 +44,11 @@ dependencies:
   override:
     - composer global require "hirak/prestissimo:^0.3"
     - composer global require "consolidation/cgr"
-    - cgr "pantheon-systems/terminus:~1" --stability beta
+    - cgr "pantheon-systems/terminus:^1"
     - terminus --version
     - mkdir -p ~/.terminus/plugins
-    - composer create-project -n -d ~/.terminus/plugins pantheon-systems/terminus-build-tools-plugin:~1
-    - composer create-project -n -d ~/.terminus/plugins pantheon-systems/terminus-secrets-plugin:~1
+    - composer create-project -n -d ~/.terminus/plugins pantheon-systems/terminus-build-tools-plugin:^1
+    - composer create-project -n -d ~/.terminus/plugins pantheon-systems/terminus-secrets-plugin:^1
   post:
     - terminus auth:login --machine-token="$TERMINUS_TOKEN"
     - terminus build-env:delete:ci -n "$TERMINUS_SITE" --keep=2 --yes