consolidate the Composer Guide, Integrated Composer and WPCM introduc…

…tions into one doc

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

@@ -3,8 +3,8 @@ title: Integrated Composer
 subtitle: Introduction
 description: Learn how to use Integrated Composer.
 tags: [composer, workflow]
-contributors: [ari, edwardangert]
-reviewed: "2022-12-13"
+contributors: [ari, edwardangert, jazzsequence]
+reviewed: "2024-09-24"
 showtoc: true
 permalink: docs/guides/integrated-composer
 contenttype: [guide]
@@ -16,7 +16,16 @@ product: [composer]
 integration: [--]
 ---
 
-Integrated Composer is a Pantheon platform feature that extends Composer <Popover content="A widely-used PHP dependency and package manager that provides an alternative, more modern way to manage the external (non-core) code used by a WordPress or Drupal site." /> functionality to WordPress and Drupal's core files, and treats them as a managed dependency. Integrated Composer enables one-click updates from the Dashboard for upstream updates and Composer dependencies on your Composer-managed Pantheon site.
+[Composer](https://getcomposer.org/) is a widely-used dependency and package manager for PHP. Composer provides an easy way to manage packages used by a WordPress site. Packages can be WordPress plugins, Drupal modules, themes, other PHP libraries and even the core CMS itself.
+
+At the most basic level, Composer requires:
+
+- A list of dependencies
+- A place to put the dependencies
+
+Understanding how Composer can be used independent of Drupal or WordPress is a good place to learn more about the general concepts. For a summary of basic usage, see [Composer's own documentation](https://getcomposer.org/doc/01-basic-usage.md).
+
+**Integrated Composer** is a Pantheon platform feature that extends Composer  functionality to WordPress and Drupal's core files, and treats them as a managed dependency. Integrated Composer enables one-click updates from the Dashboard for upstream updates and Composer dependencies on your Composer-managed Pantheon site.
 
 ## Get Started With Integrated Composer
 
@@ -42,26 +51,59 @@ You can use the [Terminus Conversion Tools Plugin](https://github.com/pantheon-s
 
 ### WordPress with Integrated Composer
 
+- Follow the [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) doc to create a new WordPress site with Integrated Composer built in.
+
+- To upgrade or migrate an existing Composer-managed WordPress site to Pantheon with Integrated Composer, please reach out to our [Professional Services](https://pantheon.io/professional-services) team for information on site migration services.
+
 <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 an Integrated Composer WordPress site with **Bedrock**.
+[WordPress (Composer Managed)](https://github.com/pantheon-systems/wordpress-composer-managed) is the recommended Composer-based WordPress upstream. The Composer-based WordPress upstreams below have been deprecated.
+
+- `wordpress-composer`
+- `example-wordpress-composer`
+- `wordpress-project`
 
 </Alert>
 
-1. [Fork the Pantheon-maintained repository](/guides/custom-upstream/create-custom-upstream#create-and-host-the-repository-remotely) from [https://github.com/pantheon-upstreams/wordpress-project](https://github.com/pantheon-upstreams/wordpress-project).
+## Dependencies
+
+Composer encourages a mental model where code not written specifically for a given project is a dependency. Only files unique to the project are tracked as part of the project's main source repository, also referred to as the canonical site repository. Dependencies for WordPress and Drupal include core, plugins, contrib modules, themes, and libraries. A single dependency, such as a theme, is referred to as a package. Review [Composer `require` and `require dev` Sections](/guides/integrated-composer/dependencies#composer-require-dev-and-require-sections) for more information on how these sections are on used on the Pantheon platform.
+
+Composer looks within [The PHP Package Repository](https://packagist.org/) for dependencies to install, which does not include Drupal or WordPress packages by default. Additional repositories must be configured for Composer to use packages not found in the default repository. Each framework provides its own respective package repository so dependencies can be managed with Composer:
+
+- WordPress: <https://wpackagist.org>
+- Drupal (Latest Version): `https://packages.drupal.org/11`
+- Drupal 7: `https://packages.drupal.org/7`
+
+## Managing Core as a Project Dependency
+
+Sites managed with Composer should use the [nested docroot](/nested-docroot) feature, which allows core to be installed within the `web` subdirectory instead of the default root directory of the site's codebase. A nested docroot is the simplest path towards reliable core updates in a Composer workflow.
+
+This is possible on Pantheon by specifying `web_docroot: true` in `pantheon.yml` file. For details, see [Serving Sites from the Web Subdirectory](/nested-docroot).
+
+When using a Pantheon-maintained upstream (either Drupal or WordPress Composer Managed), the nested docroot setting is already configured in the `pantheon.yml` file.
+
+## Next Steps
 
-1. [Add a new Custom Upstream](/guides/custom-upstream/create-custom-upstream#connect-repository-to-pantheon) on the Pantheon Dashboard.
+Here are some ways to get started using Composer for your Pantheon sites:
 
-1. Create a new WordPress site from the Upstream. Do not customize the upstream as yet.
+- Create a new [Drupal with Integrated Composer](/drupal) or [WordPress (Composer Managed](/guides/wordpress-composer/wordpress-composer-managed) site.
+- [Migrate or upgrade](/drupal-migration) an existing Drupal site to the latest version of Drupal with Integrated Composer.
+- [Convert a Standard Drupal Site to a Composer Managed Site](/guides/composer-convert).
+- Follow the [Build Tools Guide](/guides/build-tools) to learn best practices for Composer-managed sites with continuous integration (CI) workflows.
+- Review [Composer's documentation](https://getcomposer.org/doc/) to understand how Composer can be used independently of WordPress or Drupal.
+- Learn about [Roots Bedrock](https://roots.io/bedrock/), the foundation of the WordPress Composer Managed upstream.
 
-1. Navigate to the Dev environment, then click **Visit Development Site** and follow the prompts to complete the CMS installation.
+### Partial Adoption
 
-1. [Clone the site locally](/guides/local-development/configuration) and run `composer install`.
+If you're not ready to go all in with a Composer workflow and you want to see how it works on a smaller scale, follow the [Manage Some Dependencies with Composer](/guides/partial-composer) guide to get started.
 
-<Partial file="build-deploy-terminology.md" />
+<Partial file="notes/partial-composer-adoption-warning.md" />
 
 ## More Resources
 
+- [Convert a Standard Drupal Site to a Composer-Managed Site](/guides/composer-convert)
 - [WordPress on Pantheon Quick Start Guide](/guides/wordpress-pantheon/)
+- [WordPress with Composer on Pantheon](/guides/wordpress-composer/wordpress-composer-managed)
 - [Supported Drupal Versions](/supported-drupal)
 - [Drupal](/drupal)