[CMSP-386] update WordPress (Composer Managed) docs (pantheon-systems…

…#9031)

* add that wp core can be managed as a dependency

* change complete to review
users don't need to complete all the steps. they should be aware of the docs and the configuration

* add link to roots bedrock docs

* add contributor
this might not display anymore

* add missing closing parenthesis

* update docs about application.php

* fix typo

* add wordpress core location

* additional composer best practices inc updating

* remove known issue with lando and rephrase issue with subdirectory

* change the link for reporting issues back to the pantheon-systems repo

* update community slack info

* add the link for "alternate implementations"

* fix prop

* add note that WPCM is not supported by Build Tools

* explain what the WordPress Composer repository is

* remove whitespace

* update link

* use code formatting

* change the title and add contrib

* point to wpcm for forking
not wordpress-project

* remove warning to not use in production

* note that only upstream maintainers should not edit composer.json

* link to upstream management repo

* update upstream name

* upstream-config/ to upstream-configuration/

* include composer upstream-require

* spacing

* Update source/content/guides/wordpress-composer/01-introduction.md

---------

Co-authored-by: Phil Tyler <[email protected]>

source/content/guides/wordpress-composer/01-introduction.md

@@ -10,12 +10,12 @@ audience: [development]
 product: [--]
 integration: [--]
 tags: [wordpress]
-contributors: [whitneymeredith]
+contributors: [whitneymeredith,jazzsequence]
 showtoc: true
 permalink: docs/guides/wordpress-composer
 ---
 
-[Composer](https://getcomposer.org/) is a widely-used PHP dependency and package manager that provides a simplified method to manage the external (non-core) code used by a WordPress site.
+[Composer](https://getcomposer.org/) is a widely-used PHP dependency and package manager that provides a simplified method to manage packages (plugins, themes and -- with the [WordPress (Composer Managed) upstream](/wordpress-composer-managed), WordPress core itself) used by a WordPress site.
 
 At the most basic level, Composer requires:
 
@@ -25,15 +25,13 @@ At the most basic level, Composer requires:
 There are different cases for using Composer to manage dependencies on a WordPress site, including:
 
 - Manage dependencies for themes and plugins you’re currently developing
-
 - Manage the themes and plugins currently used on the site
-
+- Manage WordPress core updates
 - Total site dependency management, including custom code
 
-
 ## First Steps
 
-Complete the steps below before using this guide to create or manage updates on your Pantheon Composer-managed WordPress site.
+Review the steps below before using this guide to create or manage updates on your Pantheon Composer-managed WordPress site.
 
 <Alert title="Existing WordPress Composer Sites" type="info" >
 
@@ -47,10 +45,7 @@ Please reach out to our [Professional Services](https://pantheon.io/professional
 
 1. Review [Managing Core as Project Dependency](/guides/composer#managing-core-as-a-project-dependency).
 
-1. Review [Custom Upstream Workflow](/guides/composer#custom-upstream-workflow).
-
 ## More Resources
 
 - [Composer Fundamentals and WebOps Workflows](/guides/composer)
-
-- [Convert a Standard Drupal Site to a Composer-Managed Site](/guides/composer-convert)
+- [Roots Bedrock](https://roots.io/bedrock/)

source/content/guides/wordpress-composer/02-wordpress-composer-managed.md

@@ -19,7 +19,7 @@ anchorid: wordpress-composer-managed
 
 <Alert title="Early Access" type="info" icon="leaf">
 
-The WordPress Composer Managed upstream is available for [Early Access](/oss-support-levels#early-access) participants. Features for WordPress Composer Managed are in active development. Pantheon's development team is rolling out new functionality often while this product is in Early Access. Visit [our community Slack](https://pantheon-community.slack.com/) if you don't already have an account) to connect with other Pantheon users also using the upstream (you can sign up for the [Pantheon Slack channel here](https://slackin.pantheon.io/). Please review Pantheon's [Software Evaluation Licensing Terms](https://legal.pantheon.io/#contract-hkqlbwpxo) for more information about access to our software.
+The WordPress Composer Managed upstream is available for [Early Access](/oss-support-levels#early-access) participants. Features for WordPress Composer Managed are in active development. Pantheon's development team is rolling out new functionality often while this product is in Early Access. Visit [our community Slack](https://pantheon-community.slack.com/) if you don't already have an account) to connect with other Pantheon users also using the upstream (you can sign up for the [Pantheon Slack channel here](https://slackin.pantheon.io/)). Please review Pantheon's [Software Evaluation Licensing Terms](https://legal.pantheon.io/#contract-hkqlbwpxo) for more information about access to our software.
 
 </Alert>
 
@@ -30,7 +30,6 @@ WordPress does not natively support [Composer](https://getcomposer.org/), howeve
 ## Requirements
 
 - [PHP version](/guides/php/php-versions#verify-current-php-versions) 8.0 or greater
-
 - [Composer](https://getcomposer.org/)
 
 ## Create Your Site
@@ -57,17 +56,18 @@ Bedrock makes use of an `.env` file to store environment variables. Pantheon tak
 
 ### WordPress Config
 
-The `wp-config.php` file is located in the `web` directory. As with other WordPress sites on Pantheon, much of this is taken care of for you in `wp-config-pantheon.php`. Application-level configuration takes place in `config/application.php`. This can be referenced as a guide to understand how the constants are set up and how the `.env` files work, but modifying this file may result in merge conflicts and is not recommended. Any configuration changes should be made to your `wp-config.php` file directly.
+The `wp-config.php` file is located in the `web` directory. As with other WordPress sites on Pantheon, much of this is taken care of for you in `wp-config-pantheon.php`. Application-level configuration takes place in `config/application.php` while platform-specific updates are made in `config/application.pantheon.php`. This means that `config/application.php` can be modified for your WordPress configuration settings without fear of conflicts with the upstream. Any configuration changes should be made to your `config/appliction.php` **not** your `wp-config.php` file directly.
 
 You can learn more about WordPress configuration with Bedrock in the [Bedrock Configuration docs](https://docs.roots.io/bedrock/master/configuration/).
 
 ### Understand the WordPress Codebase
 
 Bedrock installs WordPress as a required package so updates can be managed by Composer. As such, the contents of the `wp-content` directory have been moved outside the WordPress codebase so changes can be made safely to files within those directories without conflicts. Learn more about [Bedrock's folder structure here](https://docs.roots.io/bedrock/master/folder-structure/).
 
-* Theme are installed into `web/app/themes/`
+* Themes are installed into `web/app/themes/`
 * Plugins are installed into `web/app/plugins`
 * Must-use plugins are installed into `web/app/mu-plugins`
+* WordPress core is installed into `web/wp`
 * The WordPress admin dashboard is available at `https://example.com/wp/wp-admin/`
 
 ### Using Composer to manage plugins and themes
@@ -102,19 +102,38 @@ composer require wpackagist-theme/twentytwentytwo
 composer require wpackagist-plugin/advanced-custom-fields
 ```
 
+#### Check first
+It's generally a good idea when using either Packagist or WPackagist to check the repository before `require`ing the package. If you search Packagist for a WordPress plugin or theme and don't see it, you can be sure that if it exists in the WordPress plugin or theme repository, it will be available on WPackagist. Checking WPackagist for the package can be beneficial if you want to check what versions are available.
+
+### Updating dependencies
+
+To update all Composer dependencies, run:
+
+```bash{promptUser: user}
+composer update
+```
+
+This will update all Composer-managed packages according to the version constraints in your `composer.json` file. For more information on Composer version constraints, see the [Composer documentation](https://getcomposer.org/doc/articles/versions.md).
+
+To update a specific package, run:
+
+```bash{promptUser: user}
+composer update vendor/package
+```
+
+Replace `vendor/package` with the package name you want to update. This will update only the named package to the latest version that matches the version constraints in your `composer.json` file.
+
 ## Known Issues
 
-- The WordPress Composer Managed upstream is not yet compatible with WordPress Multisite with subdirectories.
-- There is a bug with WordPress Multisite with subdomains when running the site locally with Lando and running WP-CLI commands. There is a [gist](https://gist.github.com/jazzsequence/8b68c35aa7668b77776fc1b9df216304) to fix this, which will eventually be incorporated into the upstream.
+- There is currently a known issue with WordPress Composer Managed not supporting WordPress Multisite with subdirectories. [Alternative implementations](/wordpress-ic) of WordPress with Composer may be used for this use case.
 
 ## Report an Issue
 
-Create an [issue in the Github repo](https://github.com/pantheon-upstreams/wordpress-composer-managed/issues) for the team to review and address if you discover an issue with the WordPress Composer Managed upstream.
+Create an [issue in the Github repo](https://github.com/pantheon-systems/wordpress-composer-managed/issues) for the team to review and address if you discover an issue with the WordPress Composer Managed upstream.
 
-Visit [#wordpress in our community Slack](https://pantheon-community.slack.com/archives/CT8MC5Y0K) (you can sign up for the [Pantheon Slack channel here](https://slackin.pantheon.io/) if you don't already have an account) to learn how you can enroll in our Early Access program.
+Visit [our community Slack](https://pantheon-community.slack.com/archives/CT8MC5Y0K) (you can sign up for the [Pantheon Slack channel here](https://slackin.pantheon.io/) if you don't already have an account).
 
 ## More Resources
 
 - [Bedrock Documentation](https://roots.io/bedrock/)
-
 - [Install and Configure Lando for WordPress](/guides/local-development/lando-wordpress)

source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md

@@ -10,7 +10,7 @@ audience: [development]
 product: [--]
 integration: [--]
 tags: [wordpress]
-contributors: [whitneymeredith]
+contributors: [whitneymeredith,jazzsequence]
 showtoc: true
 permalink: docs/guides/wordpress-composer/create-wp-site-composer-ci-auto-test
 ---
@@ -19,16 +19,14 @@ This section provides steps to create a new Pantheon WordPress site that will us
 
 <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**. This upstream is currently in EA.
+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**. This upstream is currently in EA and **Terminus Build Tools** does not currently support the Bedrock-based WordPress (Composer Managed) upstream.
 
 </Alert >
 
 ## Requirements
 
 - [Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin)
-
     - You must use the [Build Tools 3.x release](https://github.com/pantheon-systems/terminus-build-tools-plugin/tree/3.x) if you are using **Terminus 3**.
-
 - [PHP version](/guides/php/php-versions#verify-current-php-versions) 7.2 or greater
 
 ## Create Your Site
@@ -49,27 +47,28 @@ Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpre
     ```
 
     - This site will be based on the Pantheon-maintained [WordPress Composer repository](https://github.com/pantheon-systems/example-wordpress-composer).
+        - This repository has a similar structure to the [Bedrock-based WordPress (Composer Managed) upstream](https://github.com/pantheon-upstreams/wordpress-composer-managed) but does not use Bedrock. This repository will be deprecated in the future in favor of integrating the Bedrock-based upstream into Build Tools.
 
 1. Review the sections below for important information about your site, including an explanation of the directory structure, Continuous Integration functions, and essential configuration actions.
 
 ## Review Important Directories and Update File Paths
 
-### /web Directory
+### `/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.
 
-### /web/wp Directory
+### `/web/wp` Directory
 
-Your directories and files within the `/web` directory are stored in different locations compared to a default WordPress installation. [WordPress allows installing WordPress core in its own directory](https://wordpress.org/support/article/giving-wordpress-its-own-directory/), which is necessary when installing WordPress with Composer. The overall layout of directories in the repo is similar to [Bedrock](https://github.com/roots/bedrock).
+Your directories and files within the `/web` directory are stored in different locations compared to a default WordPress installation. [WordPress allows installing WordPress core in its own directory](https://developer.wordpress.org/advanced-administration/server/wordpress-in-directory/), which is necessary when installing WordPress with Composer. The overall layout of directories in the repo is similar to [Bedrock](https://github.com/roots/bedrock).
 
 1. Verify that the `WP_SITEURL` file is in the `/web/wp` directory to allow WordPress core functions to work correctly.
 
 1. Review the `/web/wp-config.php` file for key settings and move other files to the to the `/web/wp` directory as necessary.
 
-### composer.json File
+### `composer.json` File
 
 This project uses Composer to manage third-party PHP dependencies. Some files, such as `web/wp`, may not be visible in the repository. This is because WordPress core and its plugins are installed via Composer and ignored in the `.gitignore` file.
 
@@ -101,15 +100,15 @@ The scripts are organized into subdirectories according to their function:
 
 - `.ci/build/php` installs PHP dependencies with Composer.
 
-### Build Scripts .ci/deploy
+### 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
+## Automated Test Scripts `.ci/tests`
 
 The `.ci/tests` scripts run automated tests. You can add or remove scripts depending on your testing needs.