From 78bd99199ac1e590724f910d1c3a8114b21d5068 Mon Sep 17 00:00:00 2001 From: Chris Reynolds Date: Tue, 24 Sep 2024 15:13:23 -0600 Subject: [PATCH 1/9] consolidate the Composer Guide, Integrated Composer and WPCM introductions into one doc --- source/content/composer.md | 88 ------------------- .../integrated-composer/01-introduction.md | 62 ++++++++++--- .../wordpress-composer/01-introduction.md | 51 ----------- 3 files changed, 52 insertions(+), 149 deletions(-) delete mode 100644 source/content/composer.md delete mode 100644 source/content/guides/wordpress-composer/01-introduction.md diff --git a/source/content/composer.md b/source/content/composer.md deleted file mode 100644 index 38ee094ea0..0000000000 --- a/source/content/composer.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Composer Fundamentals and WebOps Workflows -description: Start with Composer basics then explore suggested WebOps workflows for WordPress and Drupal sites on Pantheon. -tags: [composer, workflow, updates, webops] -contenttype: [doc] -innav: [true] -categories: [update] -cms: [wordpress, drupal] -audience: [development] -product: [--] -integration: [composer] -reviewed: "2022-12-12" ---- - -[Composer](https://getcomposer.org/doc/01-basic-usage.md) is 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. - -At its primary level, Composer needs: - -- 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). - -## 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: -- Drupal (Latest Version): -- Drupal 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). - - - -## Pull Request Workflow - -In this WebOps workflow, a [Multidev](/guides/multidev) environment is created on Pantheon for each pull request branch on GitHub. Work in these environments can also be committed back to the same branch for review on GitHub. When a pull request is merged into the default branch on GitHub, the result is deployed to the Dev environment on Pantheon: - -![Multidev PR workflow](../images/pr-workflow/github-circle-pantheon.png) - -### Scaling Considerations - -We recommend the Pull Request workflow for single site use cases, and for most use cases involving larger site portfolios such as EDUs. You can create a "template" repository based off Pantheon's example repositories and customize it to your liking, then use the template to create new sites. - -However, this method does not support one-click updates in the Site Dashboard. Adopting this WebOps workflow means forgoing all other update techniques in favor of Composer. If your use case requires a simpler update strategy for non-technical site admins, this workflow could present problems scaling, or at the very least require additional training for your development team. - -To maintain a Composer-based workflow with one-click updates through the Dashboard, consider using [Integrated Composer](/guides/integrated-composer). - -## Custom Upstream Workflow - -Use [Integrated Composer](/guides/integrated-composer) to preserve the functionality of Pantheon's one-click updates from the Site Dashboard for Composer-managed sites created from a [Custom Upstream](/guides/custom-upstream). - -Updates made using Integrated Composer are only committed at the Custom Upstream level by a single repository maintainer. Updates then trickle down to sites created from the Custom Upstream as one-click updates in the Pantheon Site Dashboard. Custom Upstreams using Integrated Composer with dependencies in `upstream-configuration/composer.json` can have their own site-specific dependencies added in the top-level `composer.json` file. Custom Upstreams using Integrated Composer should avoid changing the top-level `composer.json` file after sites have been created from the Custom Upstream to avoid merge conflicts. - -If you are not using Integrated Composer to update your Custom Upstream, all dependencies must be committed. - -A shortcoming of the Custom Upstream workflow is that site-specific dependencies are likely to cause a lot of conflicts. This workflow is most practical for a large group of sites that require a single set of dependencies. You should only use this workflow if you don’t intend to use site-specific themes, modules, or plugins downstream. - -You can also prevent upstream updates by [setting an empty upstream](/guides/composer-convert/#change-upstreams). - -## Next Steps - -Here are some ways to get started using Composer for your Pantheon sites: - -- Create a new [Drupal with Integrated Composer](/drupal) 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. -- Create a new [WordPress with Integrated Composer](/guides/integrated-composer) site. - -### Partial Adoption - -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. - - - -## More Resources - -- [Convert a Standard Drupal Site to a Composer-Managed Site](/guides/composer-convert) - -- [WordPress with Composer on Pantheon](/guides/wordpress-composer) \ No newline at end of file diff --git a/source/content/guides/integrated-composer/01-introduction.md b/source/content/guides/integrated-composer/01-introduction.md index 7712495336..a48a5cceee 100644 --- a/source/content/guides/integrated-composer/01-introduction.md +++ b/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 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. + -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` -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: +- 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. - + ## 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) diff --git a/source/content/guides/wordpress-composer/01-introduction.md b/source/content/guides/wordpress-composer/01-introduction.md deleted file mode 100644 index 41467a67b2..0000000000 --- a/source/content/guides/wordpress-composer/01-introduction.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: WordPress with Composer on Pantheon -subtitle: Introduction -description: Learn more about using WordPress with Composer on Pantheon. -contenttype: [guide] -innav: [true] -categories: [dependencies] -cms: [wordpress] -audience: [development] -product: [--] -integration: [--] -tags: [wordpress] -contributors: [whitneymeredith,jazzsequence] -showtoc: true -permalink: docs/guides/wordpress-composer ---- - -[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 plugins, themes, other PHP libraries and even WordPress core itself. - -At the most basic level, Composer requires: - -- A list of dependencies -- A place to put the dependencies - -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 - -Review the steps below before using this guide to create or manage updates on your Pantheon Composer-managed WordPress site. - - - -Please reach out to our [Professional Services](https://pantheon.io/professional-services) team for information on site migration services if you have an existing Composer-managed WordPress site that you would like to migrate to the Pantheon platform. - - - -1. Review [Composer's documentation](https://getcomposer.org/doc/) to understand how Composer can be used independently of WordPress. - -1. Review [Composer Fundamentals Dependencies](/guides/composer#dependencies). - -1. Review [Managing Core as Project Dependency](/guides/composer#managing-core-as-a-project-dependency). - -## More Resources - -- [Composer Fundamentals and WebOps Workflows](/guides/composer) -- [Roots Bedrock](https://roots.io/bedrock/) \ No newline at end of file From b087eed79131aa6926751767e256edc281e8a49f Mon Sep 17 00:00:00 2001 From: Rachel Whitton Date: Mon, 14 Oct 2024 12:05:47 -0500 Subject: [PATCH 2/9] Copy audit for IC intro --- .../integrated-composer/01-introduction.md | 39 +++---------------- 1 file changed, 6 insertions(+), 33 deletions(-) diff --git a/source/content/guides/integrated-composer/01-introduction.md b/source/content/guides/integrated-composer/01-introduction.md index a48a5cceee..d5982da679 100644 --- a/source/content/guides/integrated-composer/01-introduction.md +++ b/source/content/guides/integrated-composer/01-introduction.md @@ -31,7 +31,7 @@ Understanding how Composer can be used independent of Drupal or WordPress is a g ### Drupal with Integrated Composer -- Follow the [Drupal on Pantheon](/drupal) doc to create a new Drupal site with Integrated Composer built in. +- Follow the steps to [create a new CMS site](/add-site-dashboard) to spin up a new Drupal site with Integrated Composer built in. - To upgrade or migrate an existing site to Drupal with Integrated Composer, visit the [Migrate to Drupal](/drupal-migration) guide. @@ -40,7 +40,7 @@ Understanding how Composer can be used independent of Drupal or WordPress is a g -`drupal-composer-managed` is the recommended Composer-based Drupal upstream. The Composer-based Drupal upstreams below have been deprecated. +[`drupal-composer-managed`](https://github.com/pantheon-upstreams/drupal-composer-managed) is the recommended Composer-based Drupal upstream. The Composer-based Drupal upstreams below have been deprecated. - `drupal-project` - `drupal-recommended` @@ -51,7 +51,7 @@ 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. +- Follow the steps to [create a Composer-managed WordPress site with Bedrock](/guides/wordpress-composer/wordpress-composer-managed) 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. @@ -67,7 +67,7 @@ You can use the [Terminus Conversion Tools Plugin](https://github.com/pantheon-s ## 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 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-and-require-dev-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: @@ -77,33 +77,6 @@ Composer looks within [The PHP Package Repository](https://packagist.org/) for d ## 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. +Integrated Composer sites 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 done on Pantheon by specifying `web_docroot: true` in the Pantheon configuration file. -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 - -Here are some ways to get started using Composer for your Pantheon sites: - -- 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. - -### Partial Adoption - -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. - - - -## 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) +When using a Pantheon-maintained upstream for an Integrated Composer site(either [Drupal](https://github.com/pantheon-upstreams/drupal-composer-managed) or [WordPress](https://github.com/pantheon-systems/wordpress-composer-managed)), the nested docroot setting is already configured in the `pantheon.upstream.yml` file. \ No newline at end of file From 5613a7e5246832e374eec6558a3c610473f3105d Mon Sep 17 00:00:00 2001 From: Rachel Whitton Date: Mon, 14 Oct 2024 12:11:58 -0500 Subject: [PATCH 3/9] Fix Drupal package repo --- source/content/guides/integrated-composer/01-introduction.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/content/guides/integrated-composer/01-introduction.md b/source/content/guides/integrated-composer/01-introduction.md index d5982da679..919132bc01 100644 --- a/source/content/guides/integrated-composer/01-introduction.md +++ b/source/content/guides/integrated-composer/01-introduction.md @@ -72,8 +72,7 @@ Composer encourages a mental model where code not written specifically for a giv 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: -- Drupal (Latest Version): `https://packages.drupal.org/11` -- Drupal 7: `https://packages.drupal.org/7` +- Drupal: `https://packages.drupal.org/8` ## Managing Core as a Project Dependency From e907b6d230611b10960570f4e5af7455da79c8ae Mon Sep 17 00:00:00 2001 From: Rachel Whitton Date: Tue, 15 Oct 2024 14:45:39 -0500 Subject: [PATCH 4/9] Minor copy edits to the intro page, link to new site creation content --- .../guides/integrated-composer/01-introduction.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/source/content/guides/integrated-composer/01-introduction.md b/source/content/guides/integrated-composer/01-introduction.md index 919132bc01..a9d52c48a3 100644 --- a/source/content/guides/integrated-composer/01-introduction.md +++ b/source/content/guides/integrated-composer/01-introduction.md @@ -31,7 +31,7 @@ Understanding how Composer can be used independent of Drupal or WordPress is a g ### Drupal with Integrated Composer -- Follow the steps to [create a new CMS site](/add-site-dashboard) to spin up a new Drupal site with Integrated Composer built in. +- Follow the steps to [Create a new Composer-managed CMS site](/guides/integrated-composer/create) to add a new Drupal site with Integrated Composer built in. - To upgrade or migrate an existing site to Drupal with Integrated Composer, visit the [Migrate to Drupal](/drupal-migration) guide. @@ -40,7 +40,7 @@ Understanding how Composer can be used independent of Drupal or WordPress is a g -[`drupal-composer-managed`](https://github.com/pantheon-upstreams/drupal-composer-managed) is the recommended Composer-based Drupal upstream. The Composer-based Drupal upstreams below have been deprecated. +[`drupal-composer-managed`](https://github.com/pantheon-upstreams/drupal-composer-managed) is the recommended Composer-based Drupal upstream. The following Composer-based Drupal upstreams have been deprecated: - `drupal-project` - `drupal-recommended` @@ -50,14 +50,13 @@ You can use the [Terminus Conversion Tools Plugin](https://github.com/pantheon-s ### WordPress with Integrated Composer - -- Follow the steps to [create a Composer-managed WordPress site with Bedrock](/guides/wordpress-composer/wordpress-composer-managed) to create a new WordPress site with Integrated Composer built in. +- Follow the steps to [Create a new Composer-managed CMS site](/guides/integrated-composer/create) to add 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. -[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-managed`](https://github.com/pantheon-systems/wordpress-composer-managed) is the recommended Composer-based WordPress upstream. The following Composer-based WordPress upstreams have been deprecated: - `wordpress-composer` - `example-wordpress-composer` From 5d28d7918a756e30a3e6e037fb458cccef58fb92 Mon Sep 17 00:00:00 2001 From: Chris Reynolds Date: Tue, 15 Oct 2024 13:46:27 -0600 Subject: [PATCH 5/9] [SITE-988] Consolidate WordPress Composer guide into Integrated Composer 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 --- source/content/drupal.md | 89 ----- .../guides/build-tools/02-create-project.md | 197 ++++++++++-- .../guides/integrated-composer/02-create.md | 104 ++++++ .../integrated-composer/02-dependencies.md | 91 ------ .../integrated-composer/03-dependencies.md | 303 ++++++++++++++++++ .../03-private-repo-package.md | 140 -------- .../04-one-click-updates.md | 46 --- .../integrated-composer/05-ic-upstreams.md | 40 --- .../integrated-composer/06-ic-support.md | 36 --- .../integrated-composer/06-ic-upstreams.md | 65 ++++ .../{08-ic-faq.md => 07-ic-support.md} | 47 +-- ...leshooting.md => 08-ic-troubleshooting.md} | 18 +- source/content/guides/multisite/03-config.md | 46 ++- .../02-wordpress-composer-managed.md | 143 --------- ...03-create-wp-site-composer-ci-auto-test.md | 235 -------------- .../04-multisite-configuration.md | 72 ----- .../wordpress-composer/06-wordpress-ic.md | 80 ----- .../content/partials/ic-upstream-structure.md | 8 +- source/content/supported-drupal.md | 8 + 19 files changed, 733 insertions(+), 1035 deletions(-) delete mode 100644 source/content/drupal.md create mode 100644 source/content/guides/integrated-composer/02-create.md delete mode 100644 source/content/guides/integrated-composer/02-dependencies.md create mode 100644 source/content/guides/integrated-composer/03-dependencies.md delete mode 100644 source/content/guides/integrated-composer/03-private-repo-package.md delete mode 100644 source/content/guides/integrated-composer/04-one-click-updates.md delete mode 100644 source/content/guides/integrated-composer/05-ic-upstreams.md delete mode 100644 source/content/guides/integrated-composer/06-ic-support.md create mode 100644 source/content/guides/integrated-composer/06-ic-upstreams.md rename source/content/guides/integrated-composer/{08-ic-faq.md => 07-ic-support.md} (63%) rename source/content/guides/integrated-composer/{07-ic-troubleshooting.md => 08-ic-troubleshooting.md} (88%) delete mode 100644 source/content/guides/wordpress-composer/02-wordpress-composer-managed.md delete mode 100644 source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md delete mode 100644 source/content/guides/wordpress-composer/04-multisite-configuration.md delete mode 100644 source/content/guides/wordpress-composer/06-wordpress-ic.md diff --git a/source/content/drupal.md b/source/content/drupal.md deleted file mode 100644 index b9cc9ef389..0000000000 --- a/source/content/drupal.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "Drupal on Pantheon" -description: Get started with Drupal on the Pantheon WebOps Platform. -tags: [site, D8, D9, D10] -contributors: [populist, edwardangert, whitneymeredith] -reviewed: "2022-12-09" -contenttype: [doc] -innav: [true] -categories: [cms] -cms: [drupal] -audience: [development] -product: [integrated-composer] -integration: [--] ---- - -Drupal 10 is available to all new sites, and is available as an [upgrade path for Drupal 9 sites](/drupal-10#update-a-drupal-9-site-to-drupal-10). Refer to [Drupal 10 on Pantheon](/drupal-10) for more information. - -Drupal 9 is similarly available on Pantheon to all new sites, and as an [upgrade path for Drupal 8+ sites](/drupal-migration). - -Since Drupal itself is in active development and each new version brings a number of significant changes from previous versions, this doc outlines the biggest changes and answers frequently asked questions. - -## About Drupal - -Drupal includes many of the features and layout that Drupal users are familiar with, and it removes deprecated code to help improve future Drupal development. - -The latest version of Drupal updates Drupal’s underlying dependencies like [Symfony](https://symfony.com/) and [Twig](https://twig.symfony.com/), removes several deprecated API functions in favor of better options, and allows everyone running Drupal 8.8+ an easy upgrade path to Drupal and beyond. - -## Drupal With Integrated Composer - -On the Pantheon Platform, Drupal sites use [Integrated Composer](/guides/integrated-composer), letting you deploy your site on Pantheon with one-click updates for both upstream commits and Composer dependencies, while still receiving upstream updates. - -### Site Structure - - - -### Managing Dependencies with Composer - -Learn more about working with upstream and site dependencies in the [Integrated Composer](/guides/integrated-composer) documentation. - -## Before You Begin - -- Log in to your Pantheon account. If you don't have one, [create one first](https://pantheon.io/register?docs) and familiarize yourself with [Workspaces](/guides/account-mgmt/workspace-sites-teams/workspaces) before you create a new site. - -- Set up [SSH Keys](/ssh-keys) on your local computer and Pantheon account. - -- Install and configure [Git](/guides/git/git-config) and [Composer](https://getcomposer.org/download/) on your local computer. - -- Mac users can use [Homebrew](https://brew.sh/) to install both Git, Composer, and Terminus along with their required dependencies: - - ```bash{promptUser:user} - brew install git composer pantheon-systems/external/terminus - ``` - -## Create a New Drupal Site with Integrated Composer - -[Create a new Drupal site from the Dashboard](/add-site-dashboard) as you would with any new site. Integrated Composer is built in and ready to use. - -## Upgrade or Migrate to Drupal - -To upgrade or migrate an existing Drupal site to Drupal with Integrated Composer, see the [Drupal Migration Guide](/drupal-migration). - -To check an existing site's compatibility to upgrade, visit the appropriate [Drupal Migration Guide](/drupal-migration). - -## Troubleshooting and Support - -See the appropriate [Drupal Migration Guide](/drupal-migration) for help troubleshooting common issues with Drupal with Integrated Composer. - -### Where can I report an issue? - -[Contact support](/guides/support) to report any issues that you encounter. - -### Can I Use Lando or Localdev for Drupal? - -Some users have reported success using [Lando](https://docs.lando.dev/basics/) with Drupal, but it relies on a workaround and requires extra configuration. Check the status of the [Lando repo's issue](https://github.com/lando/lando/issues/2831#issuecomment-771833900) before you continue. - -Manually update the [landofile](https://docs.lando.dev/config/lando.html#base-file) in the project folder, and set `drupal9` as the framework: - - ```yml:title=lando.yml - # Lando issue 2831 workaround for D9 - framework: drupal9 - ``` - -When you create a project with Lando from the Pantheon recipe, the `framework` will default to `drupal8` for a Drupal site. - -If you created new project with Lando, change the value for `framework` to `drupal8`, then run `lando rebuild`. - -### Site-local Drush Is Required for Drupal Sites - -Do not remove `drush/drush` from `composer.json`. If it's removed, `terminus drush` commands will fail with errors related to Twig. diff --git a/source/content/guides/build-tools/02-create-project.md b/source/content/guides/build-tools/02-create-project.md index 5e89216337..523ffa2fd7 100644 --- a/source/content/guides/build-tools/02-create-project.md +++ b/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. @@ -26,35 +26,14 @@ Substitute your chosen Git Provider and CI service in these instructions with th -## 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 ``` + + +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. + + + - Start a GitHub project with Drupal: ```bash{promptUser: user} terminus build:project:create --git=github --team='My Agency Name' d9 my-site ``` + + + +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. + + 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://.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`. + + + +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. + + + ### Troubleshooting diff --git a/source/content/guides/integrated-composer/02-create.md b/source/content/guides/integrated-composer/02-create.md new file mode 100644 index 0000000000..1be8c1b4e2 --- /dev/null +++ b/source/content/guides/integrated-composer/02-create.md @@ -0,0 +1,104 @@ +--- +title: Integrated Composer +subtitle: Create a new Composer-managed CMS site +description: Learn how to create new integrated composer Drupal and WordPress sites on Pantheon. +contenttype: [guide] +innav: [false] +categories: [dependencies] +cms: [wordpress] +audience: [development] +product: [composer] +integration: [--] +tags: [wordpress] +contributors: [whitneymeredith, jspellman814, jazzsequence] +layout: guide +showtoc: true +permalink: docs/guides/integrated-composer/create +anchorid: wordpress-composer-managed +reviewed: "2024-09-26" +--- + +## Drupal with Integrated Composer +This section provides information on how to use Drupal with Integrated Composer. + +### Create Your Site + +There are two ways you can spin up a site using WordPress Composer Managed: + +- Running the following terminus command: + + ```bash{promptUser: user} + terminus site:create --org ORG --region REGION --