Merge pull request #706 from oxyc/docs-704-1

Docs for 3.1.0

Author: geerlingguy

README.md

@@ -83,6 +83,8 @@ Notes:
   4. Open Terminal, `cd` to this directory (containing the `Vagrantfile` and this README file).
   5. Type in `vagrant up`, and let Vagrant do its magic.
 
+Once the process is complete, you will have a Drupal codebase available inside the `drupal/` directory of the project.
+
 Note: *If there are any errors during the course of running `vagrant up`, and it drops you back to your command prompt, just run `vagrant provision` to continue building the VM from where you left off. If there are still errors after doing this a few times, post an issue to this project's issue queue on GitHub with the error.*
 
 ### 3 - Configure your host machine to access the VM.

docs/deployment/composer.md

@@ -3,23 +3,23 @@ Drupal VM is configured to use `composer create-project` to build a Drupal 8 cod
 ## Using composer.json
 
 1. Copy `example.drupal.composer.json` to `drupal.composer.json` and modify it to your liking.
-2. Use the Composer build system by setting `build_composer: true` in your `config.yml` (make sure `build_makefile` is set to `false`).
+2. Use the Composer build system by setting `build_composer: true` in your `config.yml` (make sure `build_makefile` and `build_composer_project` are set to `false`).
 3. Configure `drupal_core_path` to point to the webroot directory: `drupal_core_path: {{ drupal_composer_install_dir }}/docroot`
 
 ```yaml
-build_makefile: false
+build_composer_project: false
 build_composer: true
 drupal_core_path: "{{ drupal_composer_install_dir }}/docroot"
 ```
 
-_The file set in `drupal_composer_path` (which defaults to `drupal.composer.json`) will be copied from your host computer into the VM's `drupal_composer_install_dir` and renamed `composer.json`. If you already have a composer.json within that directory, you can set `drupal_composer_path: false`._
+_The file set in `drupal_composer_path` (which defaults to `drupal.composer.json`) will be copied from your host computer into the VM's `drupal_composer_install_dir` and renamed `composer.json`. If you already have a composer.json within that directory, set `drupal_composer_path: false`._
 
 ## Using Composer when [Drupal VM is a composer dependency itself](../other/drupalvm-composer-dependency.md)
 
-In the scenario where you already have an existing `composer.json` in the root of your project, follow the usual steps for installing with a composer.json but instead of creating a `drupal.composer.json` file, disable the transfering of the file by setting `drupal_composer_path` to `false`, and change `drupal_composer_install_dir` to point to the the directory where it will be located. If `drupal_composer_path` is not truthy, Drupal VM assumes it already exists.
+In the scenario where you already have an existing `composer.json` in the root of your project, follow the usual steps for installing with a composer.json but instead of creating a `drupal.composer.json` file, disable the transfering of the file by setting `drupal_composer_path: false`, and change `drupal_composer_install_dir` to point to the the directory where it will be located. If `drupal_composer_path` is not truthy, Drupal VM assumes it already exists.
 
 ```yaml
-build_makefile: false
+build_composer_project: false
 build_composer: true
 drupal_composer_path: false
 drupal_composer_install_dir: "/var/www/drupalvm"
@@ -33,22 +33,14 @@ This is the default Drupal VM build configuration, set up by the following setti
   - Composer will build the project if `build_composer_project` is `true`, and `build_makefile` and `build_composer` are both `false`.
   - The Composer package is defined by `drupal_composer_project_package`.
   - Adjust the create-project CLI options in `drupal_composer_project_options` as well as add additional dependencies in `drupal_composer_dependencies`.
-  - Ensure that the webroot configured in the Composer package matches the one set in `drupal_core_path`.
+  - Ensure that the webroot configured in the Composer package matches the one set in `drupal_core_path`. The default is set to `web/`.
 
-With [drupal-composer/drupal-project](https://github.com/drupal-composer/drupal-project) as an example your `config.yml` settings would be:
+With [acquia/lightning-project](https://github.com/acquia/lightning-project) as an example your `config.yml` settings would be:
 
 ```yaml
-build_makefile: false
-build_composer: false
-build_composer_project: true
-
-drupal_composer_project_package: "drupal-composer/drupal-project:8.x-dev"
-# Added `--no-dev` to avoid installing development dependencies.
-drupal_composer_project_options: "--prefer-dist --stability dev --no-interaction --no-dev"
-drupal_composer_dependencies:
-  - "drupal/devel:8.*"
-
-drupal_core_path: "{{ drupal_composer_install_dir }}/web"
+drupal_composer_project_package: "acquia/lightning-project:^8.1.0"
+drupal_composer_project_options: "--prefer-dist --stability rc --no-interaction"
+drupal_core_path: "{{ drupal_composer_install_dir }}/docroot"
 ```
 
 ## Improving composer build performance

docs/deployment/drush-make.md

@@ -1,5 +1,18 @@
-Drupal VM is configured to use Composer by default to build a Drupal site on the VM inside `/var/www/drupalvm/drupal` (in a folder that's synced to your local machine, so you can work with the Drupal codebase either locally or inside the VM).
+Drupal VM is configured to use Composer by default to build a Drupal site on the VM inside `/var/www/drupalvm/drupal/web` (in a folder that's synced to your local machine, so you can work with the Drupal codebase either locally or inside the VM).
 
-If you want to build a Drupal site using a [Drush make file](http://www.drush.org/en/master/make/) instead, you can either use the `example.drupal.make.yml` file as a base, or use your own Drush make file: just place it or symlink it into the root of the Drupal VM folder with the filename `drupal.make.yml`. You can also set a separate path to the makefile using the `drush_makefile_path` variable.
+If you want to build a Drupal site using a [Drush make file](http://www.drush.org/en/master/make/) instead, set `build_composer_project: false`, `build_makefile: true` and either use the `example.drupal.make.yml` file as a base, or use your own Drush make file: just place it or symlink it into the root of the Drupal VM folder with the filename `drupal.make.yml`. You can also set a separate path to the makefile using the `drush_makefile_path` variable.
+
+```yaml
+build_composer_project: false
+build_makefile: true
+```
 
 Have a look at the defaults in `default.config.yml` and tweak the settings as you'd like in your `config.yml`, then run `vagrant up` as in the Quick Start Guide. Within a few minutes, you should have your site running and available at the `drupal_domain` configured in `config.yml`, falling back to the default `http://drupalvm.dev` set in `default.config.yml`.
+
+With the default settings the Drupal site will be built on the VM inside `/var/www/drupalvm/drupal/web` but the `web/` subdirectory is only required for `composer` based projects and you can simplify this directory structure by setting `drupal_core_path` to `/var/www/drupalvm/drupal`.
+
+```yaml
+build_composer_project: false
+build_makefile: true
+drush_core_path: "/var/www/drupalvm/drupal"
+```

docs/deployment/local-codebase.md

@@ -18,7 +18,7 @@ Set all the `build_` variables and `install_site` to `false`:
 ```yaml
 build_makefile: false
 build_composer: false
-build_composer_project: true
+build_composer_project: false
 ...
 install_site: false
 ```

docs/other/drupalvm-composer-dependency.md

@@ -15,9 +15,9 @@ Add and configure the `config.yml` anywhere you like, in this example we place i
 _Note: This will be the directory where Drupal VM looks for other local configuration files as well. Such as [`local.config.yml` and `Vagrantfile.local`](overriding-configurations.md)._
 
 ```
+├── composer.json
 ├── config/
 │   ├── config.yml
-│   ├── drupal.make.yml
 │   ├── local.config.yml
 │   └── Vagrantfile.local
 ├── docroot/
@@ -29,6 +29,16 @@ _Note: This will be the directory where Drupal VM looks for other local configur
         └── drupal-vm/
 ```
 
+Change the build strategy to use your `composer.json` file by setting:
+
+```yaml
+build_composer_project: false
+build_composer: true
+drupal_composer_path: false
+drupal_composer_install_dir: "/var/www/drupalvm"
+drupal_core_path: "{{ drupal_composer_install_dir }}/docroot"
+```
+
 If you're using `pre_provision_scripts` or `post_provision_scripts` you also need to adjust their paths to take into account the new directory structure. The examples used in `default.config.yml` assume the files are located in the Drupal VM directory. If you use relative paths you need to the ascend the directory tree as far as the project root, but using the `config_dir` variable you get the absolute path of where you `config.yml` is located.
 
 ```yaml
@@ -66,7 +76,6 @@ Your project structure should now look like this:
 ├── composer.json
 ├── config/
 │   ├── config.yml
-│   ├── drupal.make.yml
 │   ├── local.config.yml
 │   └── Vagrantfile.local
 ├── docroot/
@@ -117,7 +126,6 @@ Your directory structure should now look like this:
 ```
 ├── Vagrantfile
 ├── config/
-│   ├── drupal.make.yml
 │   ├── config.yml
 │   ├── local.config.yml
 │   └── Vagrantfile.local