[SITE-988] Consolidate WordPress Composer guide into Integrated Compo…

…ser docs (#9235)

* rename pages so they are re-ordered correctly

* remove /drupal

* add site-local drush note to supported-drupal
where we will redirect requests to /drupal

* move all the pages again

* update dependencies to include more resources and composer update docs

* move wpcm docs into integrated composer

* add ic note about code sync and upstream update composer actions

* Consolidation and blending of each framework across the guide

* Address feedback from chris

* [SITE-988] Consolidate WordPress Composer Build Tools docs with the regular Build Tools docs (#9236)

* Move most of the build-tools content for WP into the Build Tools create project doc

* [SITE-988] Consolidate WordPress Composer multisite config doc with the existing Multisite Configuration doc (#9260)

* delete the multisite config guide under wordpress-composer

* add relevant info from the wpcm multisite config to the main multisite config guide

* [SITE-988] Consolidate WPCM Custom Upstream documentation with the existing IC custom upstream documentation (#9261)

* update ic-upstream-structure partial to match wpcm

* add contributor and bump reviewed date

* update wpcm link

* add additional (cms-agnostic) info from wpcm ic doc

* add additional resources (from wpcm cu doc)

* delete the wpcm ic doc

---------

Co-authored-by: Rachel Whitton <[email protected]>

source/content/guides/build-tools/02-create-project.md

@@ -2,11 +2,11 @@
 title: Build Tools
 subtitle: Create a New Project
 description: In step two of the Build Tools guide, learn how to create a new Build Tools project.
-tags: [composer, terminus, webops, workflow, D8, D9, D10]
+tags: [composer, terminus, webops, workflow, D8, D9, wordpress]
 type: guide
 permalink: docs/guides/build-tools/create-project/
 editpath: build-tools/02-create-project.md
-reviewed: "2021-12-13"
+reviewed: "2024-09-26"
 contenttype: [guide]
 innav: [false]
 categories: [dependencies]
@@ -16,7 +16,7 @@ product: [--]
 integration: [--]
 ---
 
-In this section, we will use the Terminus Build Tools Plugin to create a new project consisting of a Git repository, a Continuous Integration service, and a Pantheon site.
+In this section, we will use the Terminus Build Tools Plugin to create a new project consisting of a Git repository, [Composer](https://getcomposer.org), a Continuous Integration (CI) service, and a Pantheon site with Automated Testing. This guide will get you started, but you will need to customize and maintain the CI/testing set up for your projects.
 
 <Alert title="Note" type="info">
 
@@ -26,35 +26,14 @@ Substitute your chosen Git Provider and CI service in these instructions with th
 
 </Alert>
 
-## Prerequisites
+## Requirements
 
-Ensure you have the latest versions of Terminus and the Terminus Build Tools plugin installed. You may want to run `terminus self:plugin:update pantheon-systems/terminus-build-tools-plugin` to ensure you have the most recent version.
-
-1. Install [Composer](/guides/composer).
-   - Verify your installation with `composer --version`:
-
-    ```bash{outputLines: 2}
-    composer --version
-    Composer version 2.1.8 2021-09-15 13:55:14
-    ```
-
-1. Install the most recent release of [Terminus](/terminus/).
-   - Verify your installation with `terminus --version`:
-
-    ```bash{outputLines: 2}
-    terminus --version
-    Terminus 3.0.1
-    ```
-
-1. [Add an SSH key](/ssh-keys) in your Personal Workspace.
-
-1. [Generate a Pantheon machine token](https://dashboard.pantheon.io/machine-token/create), then authenticate Terminus.
-
-1. Install the [Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin):
-
-   ```bash{promptUser: user}
-   terminus self:plugin:install terminus-build-tools-plugin
-   ```
+* [Composer](/guides/integrated-composer)
+* [Terminus](/terminus/)
+* [Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin)
+* [PHP version](https://docs.pantheon.io/guides/php/php-versions#verify-current-php-versions) 7.2 or greater
+* [An SSH key](/ssh-keys) in your Personal Workspace.
+* [A Pantheon machine token](https://dashboard.pantheon.io/machine-token/create), to authenticate Terminus.
 
 ### Access Tokens (Optional)
 
@@ -119,16 +98,172 @@ Modify the commands in the following examples to match your project's needs.
   terminus build:project:create --git=github --team='My Agency Name' wp my-site
   ```
 
+<Alert title="Note" type="info">
+
+Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) upstream. You can use this upstream to create a Composer-managed WordPress site with **Bedrock**. **Terminus Build Tools** does not currently support the Bedrock-based WordPress (Composer Managed) upstream.
+
+</Alert>
+
 - Start a GitHub project with Drupal:
 
   ```bash{promptUser: user}
   terminus build:project:create --git=github --team='My Agency Name' d9 my-site
   ```
+
+<Alert title="Note" type="info">
+
+Support has not yet been added for Drupal versions past 9, however you can still update to the latest Drupal version after creating the project.
+
+</Alert>
 
 The script will ask for additional information such as tokens/credentials for GitHub and the associated CI.
 
 For a list of all available command options, see the [Build Tools Project README](https://github.com/pantheon-systems/terminus-build-tools-plugin/blob/3.x/README.md#buildprojectcreate)
 
+## Review Important Directories and Update File Paths
+
+### `/web` Directory
+
+Your site is stored and served from the `/web` subdirectory located next to the `pantheon.yml` file. You must store your website in this subdirectory for a Composer-based workflow. Placing your website in the subdirectory also allows you  to store tests, scripts, and other files related to your project in your repo without affecting your web document root. It also provides additional security by preventing web access to files outside of the document root through Pantheon.
+Your files may still be accessible from your version control project if it is public. See the [`pantheon.yml` documentation](/pantheon-yml#nested-docroot) for details.
+
+1. Verify that your website is stored in the `/web` subdirectory.
+
+### `composer.json` File
+
+This project uses Composer to manage third-party PHP dependencies. Some files, such as core CMS packages inside the `/web` directory, may not be visible in the repository. This is because the CMS (Drupal or WordPress) and its plugins/modules are installed via Composer and ignored in the `.gitignore` file.
+
+Third-party dependencies, such as modules, plugins and themes, are added to the project via `composer.json` file. The `composer.lock` file keeps track of the exact dependency version. For WordPress, Composer installer-paths are used to ensure the dependencies are downloaded into the appropriate directory.
+
+1. Place all dependencies in the **require** section of your `composer.json` file.
+
+    - This includes dependencies that are only used in non-Live environments. All dependencies in the **require** section are pushed to Pantheon.
+
+1. Place all dependencies that are not a part of the web application but are necessary to build or test the project in the **require-dev** section.
+
+    - Example dependencies are `php_codesniffer` and `phpunit`. Dev dependencies are deployed to Dev and Multidev environments, but not to Test and Live environments.
+
+## Continuous Integration
+
+The scripts that run on Continuous Integration are stored in the `.ci` directory. Provider-specific configuration files, such as `.circle/config.yml` and `.gitlab-ci.yml` use these scripts.
+
+The scripts are organized into subdirectories according to their function:
+
+- Build
+- Deploy
+- Test
+
+### Build Scripts .ci/build
+
+- `.ci/build` script builds an artifact suitable for deployment.
+
+- `.ci/build/php` installs PHP dependencies with Composer.
+
+### Build Scripts `.ci/deploy`
+
+All scripts stored in the `.ci/deploy` directory facilitate code deployment to Pantheon.
+
+ - `.ci/deploy/pantheon/create-multidev` creates a new [Pantheon Multidev environment](/guides/multidev) for branches other than the default Git branch. Note that not all users have Multidev access. Please consult the [Multidev FAQ doc](/guides/multidev/multidev-faq) for details.
+
+- `.ci/deploy/pantheon/dev-multidev` deploys the built artifact to either the Pantheon Dev or a Multidev environment, depending on the Git branch.
+
+## Automated Test Scripts `.ci/tests`
+
+The `.ci/tests` scripts run automated tests. You can add or remove scripts depending on your testing needs.
+
+### Static Testing
+
+- `.ci/test/static` and `tests/unit` are static tests that analyze code without executing it. These tests are good at detecting syntax errors but not functionality errors.
+
+- `.ci/test/static/run` runs [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) with [WordPress coding standards](https://github.com/WordPress/WordPress-Coding-Standards) (for WordPress sites), [PHP Unit](https://phpunit.de/), and [PHP syntax checking](https://phpcodechecker.com/).
+
+- `tests/unit/bootstrap.php` bootstraps the Composer autoloader.
+
+- `tests/unit/TestAssert.php` provides an example Unit test.
+
+1. Create all project-specific test files in the `tests/unit` directory.
+
+### Visual Regression Testing
+
+The scripts stored in the `.ci/test/visual-regression` directory run visual regression testing through a headless browser to take screenshots of web pages and compare them for visual differences.
+
+- `.ci/test/visual-regression/run` runs [BackstopJS](https://github.com/garris/BackstopJS) visual regression testing.
+
+- `.ci/test/visual-regression/backstopConfig.js` is the [BackstopJS](https://github.com/garris/BackstopJS) configuration file.
+
+1. Update the settings in `.ci/test/visual-regression/backstopConfig.js` file for your project.
+
+    - For example, the `pathsToTest` variable determines the URLs to test.
+
+## GitHub Actions
+
+This section provides information enabling GitHub Actions for your site.
+
+The Build Tools Site will configure GitHub Actions automatically if it was passed as the selected CI when creating the site. You will need to consult advanced external resources if you're working with an existing non-Build Tools site and want to add Github Actions.
+
+The steps to enable GitHub Actions for an existing Build Tools site created with another CI (for example, CircleCI) shown below might work for you.
+
+1. Copy `.ci/.github` to `.github`.
+
+1. Add the following secrets to the Github Actions configuration:
+
+    - `ADMIN_EMAIL`
+
+    - `ADMIN_PASSWORD`
+
+    - `ADMIN_USERNAME`
+
+    - `TERMINUS_TOKEN`
+
+    - `TERMINUS_SITE`
+
+    - `SSH_PRIVATE_KEY`
+
+    - `GH_TOKEN`
+
+
+## Working Locally with Lando
+
+Complete the one-time steps below to get started using [Lando](https://docs.devwithlando.io/) for local development. Please note than Lando is an independent product and is not supported by Pantheon. Refer to the [Lando documentation](https://docs.devwithlando.io/) for more information.
+
+1. [Install Lando](https://docs.lando.dev/getting-started/installation.html) if it is not already installed.
+
+1. Clone your project repository from GitHub to your local.
+
+1. Manually create a `.lando.yml` file with your preferred configuration, based on the WordPress recipe.
+
+1. Run `lando start` to start Lando.
+
+1. Save the local site URL.
+
+    - The local site URL should look similar to: `https://<PROJECT_NAME>.lndo.site.`
+
+1. Run the command below to download dependencies.
+
+    ```bash
+    `lando composer install --no-ansi --no-interaction --optimize-autoloader --no-progress`
+    ```
+
+1. Run the command below to download the media files and database from Pantheon.
+
+    ```bash
+    `lando pull --code=none`
+    ```
+
+1. Visit the local site URL saved in the preceding steps.
+
+    - You should now be able to edit your site locally. The steps above do not need to be completed on subsequent starts. You can stop Lando with `lando stop` and start it again with `lando start`.
+
+1. Run all Composer, Terminus and wp-cli commands in Lando instead of the host machine.
+
+    - This is done by prefixing the desired command with `lando`. For example, after a change to `composer.json` run `lando composer update` rather than `composer update`.
+
+<Alert title="Warning" type="danger" >
+
+Do NOT push/pull code between Lando and Pantheon directly. All code should be pushed to GitHub and deployed to Pantheon through a continuous integration service, such as CircleCI.
+
+</Alert>
+
 ### Troubleshooting
 
 <Accordion title="Troubleshooting" id="troubleshoot-install" icon="wrench">