Drupal 8 -> 9 upgrade guide for existing Pantheon sites using Kalamuna Drupal Project

reviewed 230530

1. Prepare for upgrade

Make sure you have composer 2 running on your environment.
https://joostvanveen.com/run-composer-1-and-2-simultaniously - if you want to know how to run 2 versions of composer simultaneously, follow this article
Make sure you have PHP 7.4 on your local and MariaDB >10.4
Install Upgrade Status module on your local copy of the site, check the status of your installed modules

2. Upgrade on your local

Update your local database to the version you intend to use on the host

Based on the status, perform required actions: upgrade or patch contrib modules
Patch / update custom modules
Uninstall unused modules
Update Drupal core:
- Replace drupal/core package with drupal/core-recommended
- Remove drupal/core-dev from dev dependencies
Follow this guide to check other packages: https://www.drupal.org/docs/develop/using-composer/preparing-your-site-for-composer-2
Tun database updates on your local, export config
Check site status and smoke test the site

3. Deploy to Pantheon

Add database version to pantheon.yml
Deploy your code changes to a branch and create a multidev
Create an empty commit and push one more time to trigger environment upgrade (if you still see 5.5.30 as your DB version, please note it may take some time to upgrade)
Test your site on Pantheon

4. Upgrade to integrated composer

In a nutshell you need only 2 changes to upgrade to integrated composer: pantheon.upstream.yml and upstream-configuration folder

pantheon.upstream.yml may look something like the following

api_version: 1
web_docroot: true
# See https://pantheon.io/docs/pantheon-yml/#enforce-https--hsts for valid values.
enforce_https: full+subdomains
php_version: 7.4
database:
  version: 10.4
drush_version: 10
build_step: true
protected_web_paths:
  - /private/
  - /sites/default/files/private/
  - /sites/default/files/config/

Feel free to update pantheon.yml file to remove any non-required values that are duplicated in this new file. Make sure you keep api_version: 1 in both.

In the root of your project on the same level as your web root create a folder upstream-configuration. It will host 2 files: .gitignore and composer.json

Your composer.json in that folder may look something like that as a starter point

{
    "name": "pantheon-upstreams/upstream-configuration",
    "type": "project",
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        }
    ],
    "require": {
        "php": ">=7.3",
        "composer/installers": "^1.8",
        "drupal/core-composer-scaffold": "^9",
        "drupal/core-recommended": "^8.8 || ^9",
        "pantheon-systems/drupal-integrations": "^8 || ^9",
        "cweagans/composer-patches": "^1.0",
        "zaporylie/composer-drupal-optimizations": "^1.2"
    }
}

And .gitignore

composer.lock
/vendor/
.csslintrc
.editorconfig
.eslintignore
.eslintrc.json
.gitattributes
.ht.router.php
.htaccess
INSTALL.txt
README.txt
autoload.php
example.gitignore
index.php
robots.txt
update.php
web.config

In the CircleCI config keep the theme compilation - node related options in the CI.

Remove composer related config from the CI.

Add vendor directory to .gitignore-deploy file.

Commit to the same environment and you should have the site building with integrated composer. Test it on multidev, then deploy to dev.

Official Pantheon documentation: https://pantheon.io/docs/guides/drupal-9-migration

Review History

Who	When	Status

Who	When	Status

Bob	20230530	Current