Updating readme to be more like example-wordpress-composer (#101)

Author: stevector

README.md

@@ -1,87 +1,71 @@
 # Example Drops 8 Composer
 
-This repository can be used to set up a Composer-Managed Drupal 8 site on [Pantheon](https://pantheon.io).
-
 [![CircleCI](https://circleci.com/gh/pantheon-systems/example-drops-8-composer.svg?style=shield)](https://circleci.com/gh/pantheon-systems/example-drops-8-composer)
 [![Pantheon example-drops-8-composer](https://img.shields.io/badge/dashboard-drops_8-yellow.svg)](https://dashboard.pantheon.io/sites/c401fd14-f745-4e51-9af2-f30b45146a0c#dev/code) 
 [![Dev Site example-drops-8-composer](https://img.shields.io/badge/site-drops_8-blue.svg)](http://dev-example-drops-8-composer.pantheonsite.io/)
 
-## Overview
-
-This project contains only the canonical resources used to build a Drupal site for use on Pantheon. There are two different ways that it can be used:
+This repository is a start state for a Composer-based Drupal workflow with Pantheon. It is meant to be copied by the the [Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin) which will set up for you a brand new
 
-- Create a separate canonical repository on GitHub; maintain using a pull request workflow. **RECOMMENDED**
-- Build the full Drupal site and then install it on Pantheon; maintain using `terminus composer` and on-server development.
+* GitHub repo
+* Free Pantheon sandbox site
+* A CircleCI configuration to run tests and push from the source repo (GitHub) to Pantheon.
 
-The setup instructions vary based on which of these options you select.
+For more background information on this style of workflow, see the [Pantheon documentation](https://pantheon.io/docs/guides/github-pull-requests/).
 
-## Pull Request Workflow
 
-When using a pull request workflow, only the canonical resources (code, configuration, etc.) exists in the master repository, stored on GitHub. A build step is used to create the full Drupal site and automatically deploy it to Pantheon. This is the recommended way to use this project.
+## Installation
 
-### Setup
+### Prerequisites
 
-For setup instructions, please see [Using GitHub Pull Requests with Composer and Drupal 8](https://pantheon.io/docs/guides/github-pull-requests/).
+Before running the `terminus build:project:create` command, make sure you have all of the prerequisites:
 
-### Environment Variables
+* [A Pantheon account](https://dashboard.pantheon.io/register)
+* [Terminus, the Pantheon command line tool](https://pantheon.io/docs/terminus/install/)
+* [The Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin)
+* An account with GitHub and an authentication token capable of creating new repos.
+* An account with CircleCI and an authentication token.
 
-The [Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin) automatically configures Circle CI to build your site. The following environment variables are defined:
+You may find it easier to export the GitHub and CircleCI tokens as variables on your command line where the Build Tools Plugin can detect them automatically:
 
-- TERMINUS_TOKEN: The Terminus Machine token previously created.
-- GITHUB_TOKEN: Used by CircleCI to post comments on pull requests.
-- TERMINUS_SITE: The name of the Pantheon site that will be used to test your site.
-- TEST_SITE_NAME: Used to set the name of the test  site when installing Drupal.
-- ADMIN_EMAIL: Used to configure the email address to use when installing Drupal.
-- ADMIN_PASSWORD: Used to set the password for the uid 1 user during site installation.
-- GIT_EMAIL: Used to configure the git user’s email address for commits we make.
+```
+export GITHUB_TOKEN=[REDACTED]
+export CIRCLE_TOKEN=[REDACTED]
+```
 
-If you need to modify any of these values, you may do so in the [Circle CI Environment Variable](https://circleci.com/docs/1.0/environment-variables/) configuration page.
+### One command setup:
 
-### SSH Keys
+Once you have all of the prerequisites in place, you can create your copy of this repo with one command:
 
-A [public/private key pair](https://pantheon.io/docs/ssh-keys/) is created and added to Circle CI (the private key) and the Pantheon site (the public key). If you need to update your public key, you may do so with Terminus:
 ```
-$ terminus ssh-key:add ~/.ssh/id_rsa.pub
+terminus build:project:create pantheon-systems/example-drops-8-composer my-new-site --team="Agency Org Name"
 ```
 
-## Pantheon "Standalone" Development
+The parameters shown here are:
 
-This project can also be used to do traditional "standalone" development on Pantheon using on-server development. In this mode, the canonical repository is immediately built out into a full Drupal site, and the results are committed to the Pantheon repository. Thereafter, no canoncial repository is used; all development will be done exclusively using the Pantheon database.
+* The name of the source repo, `pantheon-systems/example-drops-8-composer`. If you are interest in other source repos like WordPress, see the [Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin).
+* The machine name to be used by both the soon-to-be-created Pantheon site and GitHub repo. Change `my-new-site` to something meaningful for you.
+* The `--team` flag is optional and refers to a Pantheon organization. Pantheon organizations are often web development agencies or Universities. Setting this parameter causes the newly created site to go within the given organization. Run the Terminus command `terminus org:list` to see the organizations you are a member of. There might not be any.
 
-When doing "standalone" development, this project can either be used as an upstream repository, or it can be set up manually. The instructions for doing either follows in the section below.
 
-### As an Upstream
+## Important files and directories
 
-Create a custom upstream for this project following the instructions in the [Pantheon Custom Upstream documentation](https://pantheon.io/docs/custom-upstream/). When you do this, Pantheon will automatically run composer install to populate the web and vendor directories each time you create a site.
+### `/web`
 
-### Manual Setup
+Pantheon will serve the site from the `/web` subdirectory due to the configuration in `pantheon.yml`, facilitating a Composer based workflow. Having your website in this subdirectory also allows for tests, scripts, and other files related to your project to be stored in your repo without polluting your web document root.
 
-Enter the commands below to create a a new site on Pantheon and push a copy of this project up to it.
-```
-$ SITE="my-site"
-$ terminus site:create $SITE "My Site" "Drupal 8" --org="My Team"
-$ composer create-project pantheon-systems/example-drops-8-composer $SITE
-$ cd $SITE
-$ composer prepare-for-pantheon
-$ git init
-$ git add -A .
-$ git commit -m "Initial commit"
-$ terminus  connection:set $SITE.dev git
-$ PANTHEON_REPO=$(terminus connection:info $SITE.dev --field=git_url)
-$ git remote add origin $PANTHEON_REPO
-$ git push --force origin master
-$ terminus drush $SITE.dev -- site-install --site-name="My Drupal Site"
-$ terminus dashboard:view $SITE
-```
-Replace my-site with the name that you gave your Pantheon site. Customize the parameters of the `site:create` and `site-install` lines to suit.
+#### `/config`
+
+One of the directories moved to the git root is `/config`. This directory holds Drupal's `.yml` configuration files. In more traditional repo structure these files would live at `/sites/default/config/`. Thanks to [this line in `settings.php`](https://github.com/pantheon-systems/example-drops-8-composer/blob/54c84275cafa66c86992e5232b5e1019954e98f3/web/sites/default/settings.php#L19), the config is moved entirely outside of the web root.
+
+### `composer.json`
 
-Type `terminus drush sitename.env -- uli` to get a user reset link to set a username and password for an admin.
+If you are just browsing this repository on GitHub, you may notice that the files of Drupal core itself are not included in this repo.  That is because Drupal core and contrib modules are installed via Composer and ignored in the `.gitignore` file. Specific contrib modules are added to the project via `composer.json` and `composer.lock` keeps track of the exact version of each modules (or other dependency). Modules, and themes are placed in the correct directories thanks to the `"installer-paths"` section of `composer.json`. `composer.json` also includes instructions for `drupal-scaffold` which takes care of placing some individual files in the correct places like `settings.pantheon.php`.
 
-### Installing Drupal
+## Behat tests
 
-Note that this example repository sets the installation profile to 'standard' in settings.php, so that the installer will not need to modify the settings file. If you would like to install a different profile, modify settings.php appropriately before installing your site.
+So that CircleCI will have some test to run, this repository includes a configuration of Behat tests. You can add your own `.feature` files within `/tests/features/`.
 
-### Updating Your Site
+## Updating your site
 
 When using this repository to manage your Drupal site, you will no longer use the Pantheon dashboard to update your Drupal version. Instead, you will manage your updates using Composer. Updates can be applied either directly on Pantheon, by using Terminus, or on your local machine.
 
@@ -96,3 +80,11 @@ Other commands will work as well; for example, you may install new modules using
 #### Update on your local machine
 
 You may also place your site in Git mode, clone it locally, and then run composer commands from there.  Commit and push your files back up to Pantheon as usual.
+
+
+
+
+
+
+
+