webchick / drupal8to9-upgrade

Upgrade Drupal 8 > 9 in 20 Minutes

This repository contains an example Drupal 8 application to be used for the "Upgrade Drupal 8 > 9 in 20 Minutes" workshop.

To upgrade this site to Drupal 9, proceed to the following directions.

Prepare for the Workshop

The "hands on" portion of the workshop will be performed in Acquia's recommended development environment, Acquia Cloud IDE. If you're already an Acquia customer you may use your existing Cloud Platform application. In any case, you will be invited to join our "Acquia Learning Services" sandbox application where you are free to create a Cloud IDE for this workshop.

1. When you receive an invite to the Acquia Learning Services application from Acquia via email, accept the invite. You will be prompted to login or create an Acquia Cloud Platform account, and you will then be prompted to accept the invitation for that account.
2. On the "Acquia Learning Services" application on cloud.acquia.com, create a new Cloud IDE for yourself by clicking Actions > Create Cloud IDE and give it a Label such as Drupal 9 Upgrade Workshop. Please only create one IDE, as the number available are limited. This IDE will be available for 3 days following the workshop.
3. The IDE will take 10-15 minutes to provision. You will see it listed alongside your other environments such as Dev, Stage, and Prod. In the mean time, feel free to peruse the Cloud IDE Product Documentation to familiarize yourself with the user interface.
4. Once provisioning is complete, click Launch Cloud IDE to login to the Cloud IDE.
5. If you'd like, you can complete steps 1-3 in the "Workshop Walkthrough" below so that you join this workshop with Drupal already installed on your IDE.

Workshop Walkthrough

Set up your Cloud IDE with a Drupal 8 site

1. Login to your Cloud IDE.
2. Open a Terminal pane in the IDE browser tab by clicking Terminal > New Terminal. You will start off in the ~/project directory, which is where your Drupal application will live.
3. In the Terminal pane of the Cloud IDE, Run:

   git clone https://github.com/grasmash/drupal8to9-upgrade .
   composer install
   drush site-install -y

4. If you'd like, you may login to the new Drupal site and validate that it is working as expected. Just drush user-login and cmd+click the link. The site is called "Drush Site-Install" and has no content yet.

Add the "Upgrade Status" tool to your Drupal 8 site

Next, we will download the Upgrade Status module. This will assist us with identifying what changes will be necessary to make our Drupal 8 site Drupal 9 compatible.

1. To add Upgrade Status module (and all of its dependencies) to your site's development dependencies, run:

   composer require drupal/upgrade_status
   composer require drupal/core-dev:8.9.0 --dev -W
   drush pm-enable upgrade_status -y

2. If you're not already logged into your Drupal site, run drush user-login and cmd+click the link to login.
3. Visit /admin/reports/upgrade-status on the Drupal site. You can navigate there by first clicking "Reports" in the admin menu and then clikcing "Upgrade Status."

Upgrade Contributed modules

1. Note on the "Upgrade Status" report that the Token module is listed as incompatible with Drupal 9. However, that notice also indicates under the "Plan" column that "8.x-1.7+ is Drupal 9 compatible.". We will therefore update the Token module to at least 8.x-1.7.

2. In Drupal's Semantic versioning for Composer, the canonical version 8.x-1.7 is transformed to 1.7.0. We will therefore use a version constraint of "drupal/token": "^1.7.0" to instruct Composer to install a minimum version of Token 1.7.0. Upgrade the token module by opening composer.json in the IDE "files" pane and changing the following files content:

   "drupal/token": "1.5.0",

   To:

   "drupal/token": "^1.7.0",

   

3. Run composer update to update your dependencies (and composer.lock) to match your newly defined requirements.

4. Run drush cache-rebuild and reload the Upgrade Status report. You should see that Token has now been moved under a "Drupal 9 Compatible" heading and the row is green.

Your contributed modules are now Drupal 9 compatible!

Upgrade custom code

1. The second module is an example custom module called my_special_module. This module is NOT Drupal 9 compatible. Run:

    drush pm-enable my_special_module -y

2. Visit /admin/reports/upgrade-status on the Drupal site again. Check the row for My special module, and click Scan selected.
3. Click on the "2 problems" link for the "My special module" module:
4. You'll see details on exactlly what needs to be changed in the module:
5. Open docroot/modules/custom/my_special_module/my_special_module.info.yml and change:

   core: 8.x

   To:

   core_version_requirement: ^8 || ^9

6. Open docroot/modules/custom/my_special_module/my_special_module.module and change:

   drupal_set_message(t("Welcome @name! You are a special person.", ['@name' => $account->getAccountName()]));

   To:

   \Drupal::messenger()->addMessage(t("Welcome @name! You are a special person.", ['@name' => $account->getAccountName()]));

7. Re-scan the module once more in the Upgrade Status report. This time, it too moves down to the "Drupal 9 Compatible" fieldset!

Upgrade Drupal core.

Now that all of our modules are Drupal 9 compatible, the last step is to upgrade Drupal core.

1. Open composer.json in the IDE.
2. Change:

   "drupal/core-composer-scaffold": "^8.9.0",
   "drupal/core-recommended": "^8.9.0",
   ...
   "drupal/core-dev": "^8.9.0",

   To:

   "drupal/core-composer-scaffold": "^9.2.0",
   "drupal/core-recommended": "^9.2.0",
   ...
   "drupal/core-dev": "^9.2.0",

3. Run:

   composer update
   drush cache-rebuild
   drush updatedb -y

4. You're done! To verify, go to Reports > Status report and verify that your Drupal version reads 9.2.0-dev instead of 8.9.14!

Cleanup

Now that we've successfully upgraded to Drupal 9, we can remove some of the tools that we installed.

drush pm-uninstall upgrade_status
composer remove drupal/upgrade_status
composer remove drupal/core-dev --dev
composer update

After doing this, you'll see that the Upgrade Status report and module are both gone, and your site is back to the way it was in production.

Troubleshooting

I get an error "Your requirements could not be resolved to an installable set of packages."

This is caused by a typo in your composer.json, for example specifying 9.2.0 instead of ^9.2.0. Check the results carefully... every character matters! :)

I see notices when running composer update about Package container-interop/container-interop being abandoned

Don't sweat it... this is coming from Drupal core because of one of its upstream dependencies; nothing you're doing wrong, and it's a harmless error.