Skip to main content
Last Reviewed: 2022-12-13

Switch from Drupal to Drupal Composer Managed Upstream

Switch to the new Pantheon upstream to take advantage of the new structure and future updates.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

In this guide, we will convert an existing site from the Drupal (drupal9) upstream to the new Drupal Composer Managed (drupal-composer-managed) upstream.

Overview

Drupal sites created on the platform prior to November 30, 2021 use the latest Drupal upstream. Drupal sites created on the platform prior to May 4, 2021 use the Drupal Recommended upstream.

Based on community needs, we have released a new upstream. Drupal Composer Managed is now the default Drupal upstream on the platform and users are encouraged to switch to it to take advantage of the improved structure and updates.

The goals of this conversion doc include the following:

  • Configure the site to use the new upstream.
  • Apply the upstream changes.
  • Resolve any merge conflicts that might arise during the conversion process.

Will This Guide Work for Your Site?

You must confirm that your site meets the following requirement before you continue:

Use Terminus to Confirm the Drupal Upstream

Run the command terminus site:info $SITE to display the site's basic information and properties.

The following values indicate that a site is using a drupal9 upstream:

  • The Framework is drupal8
  • The Upstream includes https://github.com/pantheon-upstreams/drupal-project or https://github.com/pantheon-upstreams/drupal-recommended

The following is an abridged example of the output for the terminus site:info $SITE command, if the site upstream is set to drupal9:

Note

If you have access to Multidev, you could also do this process in an automated way via Terminus using the Conversion Tools plugin command conversion:update-from-deprecated-upstream and following instructions after running that command.

Prepare the Local Environment

  1. Review our documentation on Git, Composer, and Terminus, and install and configure them on your local computer. Pantheon requires Composer 2 at minimum.

    • Mac users can use Homebrew to install Git, Composer, and PHP, along with their required dependencies. Restart the shell or terminal environment after entering the following command:
    • Windows users can install Composer and Git, and may need to install XAMPP or similar to satisfy some dependencies.

  2. Set the temporary variable $SITE in your terminal session to match the name of your site.

    This doc uses several commands that use the temporary command line alias, $SITE, to make entering command examples easier. Refer to the steps further in this doc to see which sites should be aliased (it may be more than one), then replace anita-drupal in this example:

  3. Create a new folder to use while working on the migration. This folder will contain two subdirectories that you'll create in the next sections, one for the site on the former platform, and one for the Pantheon site.

Apply All Available Upstream Updates

  1. Use Terminus to list all available updates:
  1. Apply any available updates using the command line or the Pantheon Dashboard:

Switch to Drupal with Composer Upstream

Change the upstream that your site is tracking with the following command:

Follow the drupal-composer-managed upstream to keep your site current with any general configuration changes recommended by Pantheon.

Apply New Upstream Updates

After you complete the upstream change, you need to apply the available upstream updates. Use the Pantheon Dashboard in the Dev environment to apply updates. If this is not successful, continue to the next section for help resolving with merge conflicts.

Solving Merge Conflicts When Applying Upstream Updates

Conflicts can occur when a modified file in your site's codebase does not align with changes made to the same file in the site's upstream.

If you receive an error that you have conflicts while updating upstream files, resolve using the -Xtheirs flag. This will automatically resolve the conflict with a preference for upstream changes. Alternatively, you can choose to manually resolve conflicts to fix this issue.

This is safe to run if you don't have your own changes in any of the conflicting files, such as problems with .gitignore.

Check that the files are correct before going forward to ensure no bugs are introduced.

You will be in the Drupal with Composer upstream after you apply the upstream updates.

More Resources