integrated-composer.md

Integrated Composer Early Access Documentation

Date last updated: April 7, 2020

Project status: In development

Introduction

Welcome to Early Access for Pantheon’s Integrated Composer solution!

This documentation has everything you need to get started and provide feedback as we continue to develop this feature.

Key Benefits:

• Lean repository & zero build artifacts on master branch
• 1-click updates for both upstream commits and Composer dependencies
• Integrated build step & no need for 3rd-party integrations
• Downstream sites can be customized and continue to receive upstream updates

Caveats:

• Not meant for production use (yet)
• Sites must be created with ic-demo-2020- site name prefix
• Sites will be deleted without notice
• Only tested with Drupal 8

Other existing solutions may be a better fit for your needs. For example, if your continuous integration requires automated testing, or operations other than running composer update or composer install, consider integrating with a 3rd-party CI service using Terminus Build Tools.

Getting Started

Create Custom Upstream & Create a New Site

1. Fork the Pantheon-maintained experimental Drupal 8 template: pantheon-upstreams/drupal-project. For detailed steps see the general documentation on custom upstreams: Create and Host the Repository Remotely.
2. Add a new custom upstream on the Pantheon dashboard. For details see Connect Repository to Pantheon.
3. Create a new site from your new upstream with the magic site name prefix ic-demo-2020
4. Install the site in Dev and verify it’s working.
5. Clone the site locally and run composer install

Upstream and Site Structure

The upstream has the following directory structure:

upstream/
   |- composer.json
.gitignore
README.md
composer.json
pantheon.upstream.yml

• Two composer.json files facilitate customization of both the upstream and individual sites and enable 1-click updates, without inherent merge conflicts.
• Upstream customizations live in upstream/composer.json.
• Site-level customizations live in the root-level composer.json.
• When a site is created, Pantheon runs composer install, generates a composer.lock file and commits it back to the site’s code repository.
• The build_step_demo: true directive in pantheon.upstream.yml enables the build step. This name is temporary and will change.
• Build artifacts are stored on a git tag, not on the master branch or Multidev branch.

Adding Dependencies to Your Upstream

1. Start with a local clone of your upstream repository
2. Change into the upstream directory
3. Run composer require drupal/pkg-name --no-update. Note that --no-update will make Composer run faster
4. Run composer config version to confirm your current version. You should see output like: 1.0.0
5. Run composer config version x.y.z to increment the version number. Replace x.y.z with something like 1.0.1. Incremeneting the version is an important step, otherwise the updated dependencies will be ignored by downstream sites.
6. Commit and push

Applying 1-click Updates

1. From the Code tab in the Dev or Multidev environment select Check updates
2. Select Apply updates

Both of these operations require running Composer and may take several minutes.

Adding Dependencies to an Individual Site

1. Clone git repo from Pantheon site dashboard
2. Run composer install (optional)
3. Add new dependency locally, e.g. composer require drupal/bootstrap
4. Commit composer.json and composer.lock and push

• Pantheon will run Composer, generate build artifact, and deploy it to your Dev or Multidev

Remove Dependency from an Individiual Site

1. Use composer remove vendor/package from a local clone of your site.
2. Commit and push

Troubleshooting / FAQ

What Composer commands does Pantheon run?

Pantheon automatically runs composer install and composer update with the following syntax:

composer update:

composer --no-cache --no-interaction --no-progress --prefer-dist update

composer install:

composer --no-cache --no-interaction --no-progress --prefer-dist install

See what’s changed, excluding composer.lock

git diff -- . ':(exclude)composer.lock'

Submitting Feedback

Please submit feedback by April 17th. We will send out a survey. In the meantime, if you experience any issues, please let us know using this form.

New WordPress tempalte project: https://github.com/pantheon-upstreams/wordpress-project

Same basic instructions as Drupal.

To add a WordPress plugin you’ll want to do something like : composer require wpackagist-plugin/akismet

We have important patches that sometimes present interaction for 'discard changes' when a package changes, but when there is a patch applied, they require a 'yes' response. I think this would be the most-desired default behavior on the platform. Documentation says this can be changed in different ways including an environment setting, but IMO the best for user control would be to place "discard-changes": true in "config" in composer.json.