Skip to main content
Log inGet free account
Last Reviewed: December 13, 2022

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:

    terminus site:info $SITE
------------------ -------------------------------------------------------------------------------------
ID                 abdc3ea1-fe0b-1234-9c9f-3cxeAA123f88
Name               anita-drupal
Label              AnitaDrupal
Created            2019-12-02 18:28:14
Framework          drupal8
...
Upstream           e96c6794-77fe-4931-9a20-48a2fe1a3789: https://github.com/pantheon-upstreams/drupal-project
...
------------------ -------------------------------------------------------------------------------------
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. Note: Terminus 3 should be used for PHP >= 8.0. Restart the shell or terminal environment after entering the following command:

      brew install git composer php

    • 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:

    export SITE=anita-drupal && echo "New alias set as $SITE"
    How to Use Terminus to Find the Site Name

    Use terminus site:list for a list of sites you have access to:

    terminus site:list
--------------------------- --------------------- ------------- ----------------------------------- -------------------- --------------------- ------------- ------------
Name                        ID                    Plan          Framework          Region           Owner                Created               Memberships   Is Frozen?
--------------------------- --------------------- ------------- ------------------- ---------------- -------------------- --------------------- ------------- ------------
anita-drupal                abdc80ce-286c-1234-   Sandbox       drupal8             Canada           3374708c-987e-1234   2020-12-15 19:40:42   d3ecc20c-395a falseanita-wordpres              abdc9954-fab2-1234-   Sandbox       wordpress           United States    c96ddb25-336a-1234   2020-09-02 07:18:51   d3ecc20c-395a false

    The site name is listed under Name. In this example, the site name is anita-drupal.

  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:

    terminus upstream:updates:list $SITE.dev
[warning] There are no available updates for this site.

  2. Apply any available updates using the command line or the Pantheon Dashboard:

    terminus upstream:updates:apply $SITE.dev --updatedb

Switch to Drupal with Composer Upstream

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

terminus site:upstream:set $SITE drupal-composer-managed

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.

git pull -Xtheirs https://github.com/pantheon-upstreams/drupal-composer-managed.git main
# resolve conflicts
git push origin master

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