diff --git a/source/content/guides/integrated-composer/06-ic-upstreams.md b/source/content/guides/integrated-composer/06-ic-upstreams.md index 974ba2b0d8..8657828dff 100644 --- a/source/content/guides/integrated-composer/06-ic-upstreams.md +++ b/source/content/guides/integrated-composer/06-ic-upstreams.md @@ -3,8 +3,8 @@ title: Integrated Composer subtitle: Use an Upstream with Integrated Composer description: Learn how to use an Upstream with Integrated Composer. tags: [composer, workflow] -contributors: [ari, edwardangert] -reviewed: "2022-12-13" +contributors: [ari, edwardangert, jazzsequence] +reviewed: "2024-10-15" showtoc: true permalink: docs/guides/integrated-composer/ic-upstreams contenttype: [guide] @@ -21,7 +21,7 @@ This section provides information on how to use an Upstream with Integrated Comp ## Upstreams -An Upstream refers to the source code in Git that shares a Git history with "downstream" individual sites made from it. Upstreams includes the core code for [Drupal](https://github.com/pantheon-upstreams/drupal-composer-managed), [WordPress](https://github.com/pantheon-upstreams/wordpress-project), and some customizations for the Pantheon platform. +An Upstream refers to the source code in Git that shares a Git history with "downstream" individual sites made from it. Upstreams includes the core code for [Drupal](https://github.com/pantheon-upstreams/drupal-composer-managed), [WordPress](https://github.com/pantheon-upstreams/wordpress-composer-managed), and some customizations for the Pantheon platform. ### Upstream and Site Structure @@ -29,12 +29,37 @@ An Upstream refers to the source code in Git that shares a Git history with "dow +## Create Your Integrated Composer Custom Upstream + +Follow the steps in this section to create a custom upstream that uses Integrated Composer. + +1. Fork the Pantheon-maintained [WordPress (Composer Managed)](https://github.com/pantheon-upstreams/wordpress-composer-managed) or [Drupal Composer Managed](https://github.com/pantheon-upstreams/drupal-composer-managed) upstream repository. + +1. [Connect your repository](/guides/custom-upstream/create-custom-upstream#connect-repository-to-pantheon) to Pantheon. + +1. Update the **require** section of the root `/composer.json` file to match the name you chose in the preceding step. + +## Add and Remove Packages + +1. Use `composer require`in the `upstream-configuration` directory (or `composer upstream-require` if using `upstream-management`) to edit the upstream `composer.json` file. + - The WordPress (Composer Managed) repository places a theme in the upstream `composer.json` file. This works well for downstream sites that all use the same theme. You should remove themes from the upstream `composer.json` file if you do not intend to use the upstream to lock downstream sites into a particular theme. You cannot remove installed packages from downstream sites if the packages were included from the upstream site. + +## Maintain Your Integrated Composer Fork + + There are some special considerations to keep in mind if you intend to make modifications to your upstream based on this repository. + +1. Increase the version number listed in the `upstream-configuration/composer.json` file each time you make edits. + - Composer checks the contents of the root `/composer.json` file for changes that should be pushed to your upstream configuration. + +1. Verify your changes to the `upstream-configuration/composer.json` file by running `composer install` or `composer update` in the `upstream-configuration` directory. + - Be careful not to rely on ["root-only" properties of composer.json](https://getcomposer.org/doc/04-schema.md). + ## More Resources - [Custom Upstreams](/guides/custom-upstream) - - [Autopilot for Custom Upstreams](/guides/autopilot-custom-upstream) - - [Migrate a Custom Upstream to Drupal](/guides/drupal-hosted-createcustom) - - [Pantheon YAML Configuration Files](/pantheon-yml) +- [Best Practices for Maintaining Custom Upstreams](/guides/custom-upstream/maintain-custom-upstream) +- [Composer Fundamentals and WebOps Workflows](/guides/composer) +- [Create a Composer-managed WordPress Site with Bedrock](/guides/wordpress-composer/wordpress-composer-managed) diff --git a/source/content/guides/wordpress-composer/06-wordpress-ic.md b/source/content/guides/wordpress-composer/06-wordpress-ic.md deleted file mode 100644 index 08d4885780..0000000000 --- a/source/content/guides/wordpress-composer/06-wordpress-ic.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: WordPress with Composer on Pantheon -subtitle: Create a Composer-managed WordPress Site with Integrated Composer and Custom Upstreams -description: Learn how to use Integrated Composer and Custom Upstreams with WordPress on Pantheon. -contenttype: [guide] -innav: [false] -categories: [dependencies] -cms: [wordpress] -audience: [development] -product: [--] -integration: [--] -tags: [wordpress] -contributors: [whitneymeredith,jazzsequence] -showtoc: true -permalink: docs/guides/wordpress-composer/wordpress-ic ---- - -[Integrated Composer](/guides/integrated-composer) is a Pantheon platform feature. Integrated Composer extends Composer functionality to WordPress core files and treats them as a managed dependency. Integrated Composer lets you deploy your site on Pantheon with one-click updates for both upstream commits and Composer dependencies, while still receiving upstream updates. - -## WordPress with Integrated Composer on Pantheon - -Pantheon maintains a [Composer-enabled WordPress Upstream](https://github.com/pantheon-upstreams/wordpress-composer-managed) repository. This is the recommended starting point for forking new upstreams that work with Pantheon's Integrated Composer build process. - -This repository is still under active development. As with all custom upstreams, you are responsible for maintaining your custom upstream and making sure it is up-to-date with the source upstream. There is no guarantee of backwards compatibility. - -Pantheon upstreams influence the Composer packages that are included in downstream sites by including two `composer.json` files in this repository: - -- The root `/composer.json` file is owned by the downstream site. Maintainers of _custom upstreams_ should avoid editing this file. This allows the downstream site maintainer to adjust the `/composer.json` file without creating potential conflicts when merging upstream updates. - -- The `upstream-configuration/composer.json` file is owned by the upstream maintainer. It is included by the root `composer.json` file, and allows upstreams to add or remove packages from downstream sites. Changes are automatically incorporated into the downstream site whenever upstream updates are applied. Pantheon has developed a tool to help you work with upstream configuration called [upstream-management](https://packagist.org/packages/pantheon-systems/upstream-management), which you can install by using `composer require pantheon-systems/upstream-management:^1`. - -## Create Your WordPress Integrated Composer Site - -Follow the steps in this section to create a new WordPress site using Integrated Composer and Upstream. - -1. Fork the [Pantheon-maintained WordPress Upstream repository](https://github.com/pantheon-upstreams/wordpress-composer-managed). - -1. [Connect your repository](/guides/custom-upstream/create-custom-upstream#connect-repository-to-pantheon) to Pantheon. - -1. Update the **require** section of the root `/composer.json` file to match the name you chose in the preceding step. - -## Add and Remove Packages - -1. Use `composer require`in the `upstream-configuration` directory (or `composer upstream-require` if using `upstream-management`) to edit the upstream `composer.json` file. - - The repository template places a theme in the upstream `composer.json` file. This works well for downstream sites that all use the same theme. You should remove themes from the upstream `composer.json` file if you do not intend to use the upstream to lock downstream sites into a particular theme. You cannot remove installed packages from downstream sites if the packages were included from the upstream site. - -## Maintain Your Integrated Composer Fork - - There are some special considerations to keep in mind if you intend to make modifications to your upstream based on this repository. - -1. Increase the version number listed in the `upstream-configuration/composer.json` file each time you make edits. - - Composer checks the contents of the root `/composer.json` file for changes that should be pushed to your upstream configuration. - -1. Verify your changes to the `upstream-configuration/composer.json` file by running `composer install` or `composer update` in the `upstream-configuration` directory. - - Be careful not to rely on ["root-only" properties of composer.json](https://getcomposer.org/doc/04-schema.md). - -## Manage Your WordPress Integrated Composer Site - -1. Review the [Integrated Composer Guide](/guides/integrated-composer) for information on how to: - - [Manage Core as a Project Dependency](/guides/composer#managing-core-as-a-project-dependency) - - [Serve Sites from the Web Subdirectory](/nested-docroot) - - [Add a Dependency to an Individual Site](/guides/integrated-composer#add-a-dependency-to-an-individual-site) - - [Add a Package from a Private Repository](/guides/integrated-composer/private-repo-package) - - [Apply One-click Updates](/guides/integrated-composer/one-click-updates) - - [Add dependencies to your Upstream](/guides/integrated-composer/ic-upstreams) - -1. Review the [Custom Upstreams](/guides/custom-upstream/maintain-custom-upstream) documentation to learn how to: - - [Test and Release Pantheon Core Updates](/guides/custom-upstream/maintain-custom-upstream#test-and-release-pantheon-core-updates) - - [Automatically Resolve Conflicts from the Command Line](/guides/custom-upstream/maintain-custom-upstream#automatically-resolve-from-the-command-line) - - [Tips and Tricks for Maintaining Custom Upstreams](/guides/custom-upstream/maintain-custom-upstream#delete-custom-upstream) - - [Delete a Custom Upstream](/guides/custom-upstream/maintain-custom-upstream#delete-custom-upstream) - -1. Review the [Pantheon YAML Configuration Files](/pantheon-yml) documentation to learn about: - - [Custom Upstream Configurations](/pantheon-yml#custom-upstream-configurations) - -## More Resources - -- [Best Practices for Maintaining Custom Upstreams](/guides/custom-upstream/maintain-custom-upstream) -- [Composer Fundamentals and WebOps Workflows](/guides/composer) -- [Create a Composer-managed WordPress Site with Bedrock](/guides/wordpress-composer/wordpress-composer-managed) diff --git a/source/content/partials/ic-upstream-structure.md b/source/content/partials/ic-upstream-structure.md index 8c4a55384d..b49ead3a3d 100644 --- a/source/content/partials/ic-upstream-structure.md +++ b/source/content/partials/ic-upstream-structure.md @@ -16,18 +16,18 @@ code/ ├─ composer.json └─ pantheon.upstream.yml ├─ README.md -└─ upstream-configuration/ or upstream-config/ for WordPress +└─ upstream-configuration/ └─ composer.json └─ web/ └─ sites/ for Drupal - └─ wp-content/ for WordPress + └─ app/ for WordPress (Composer Managed) (plugins, themes, and uploads) + └─ wp/ for WordPress (Composer Managed) (core files) ``` - `.gitignore`: Prevents [build artifacts](/guides/integrated-composer#build-and-deploy-terminology) generated by Composer from being committed to the upstream or site code repositories. Note that changing the tracking status of Composer-managed files and directories can result in build failures or lead to unexpected errors. - `composer.json`: The two different `composer.json` files allows you to customize individual sites without inherent merge conflicts and enables one-click updates. - Root-level: Site-level customizations. - - Drupal: `upstream-configuration/` or WordPress: `upstream-config/`: - - `composer.json`: Composer automatically updates `composer.json` with customizations for the upstream. Avoid manually modifying this file. + - `upstream-configuration/`: Composer automatically updates `composer.json` with customizations for the upstream. Avoid manually modifying this file. - `pantheon.upstream.yml`: The `build_step: true` directive in `pantheon.upstream.yml` enables the build step. When a site is created, Pantheon runs `composer install`, generates a `composer.lock` file, and commits it back to the site’s code repository. To avoid potential merge conflicts after applying an upstream update, do **not** commit the `composer.lock` file from your upstream root to the upstream repository.