How to Prepare Your Website for its Drupal 9 Upgrade

Submitted by jyde on Mon, 10/25/2021 - 16:30

In the coming weeks, the following changes will automatically be applied:

  • All CERN websites will move to the OpenShift infrastructure; and
  • Drupal 8.x websites will be upgraded to Drupal 9.

Where the former is very unlikely to require any action from any end-users, the Drupal upgrade will require some (minor) changes for a subset of websites using custom themes and modules. Indeed, the Web Team has already made sure that the CERN Theme, the CERN Override Theme, and all CERN Modules are Drupal 9 ready. As such, unlike the Drupal 7 to Drupal 8 migration, the upgrade to Drupal 9 will be significantly easier and largely automated for the vast majority of websites. If your website uses custom themes or modules, this guide will outline the steps necessary to check and otherwise prepare your website for Drupal 9.


Checking Your Website

We recommend everyone to access their website(s) following the migration to the OpenShift cloud infrastructure.

As part of the migration to the cloud infrastructure, a new report tool has been made available to all website owners.

Access to your website, log in, click on the menu item Reports and select Upgrade status.

This loads a number of tabs:

The REMOVE tab displays all modules available but not currently installed on your website.

In many cases, there can be a long list of modules listed. Rest assured that you can safely ignore this tab. However, while you may proceed without further action, it is generally good practice to properly remove modules that are no longer needed. We thus encourage experienced users to do this by mounting their website's WebDAV before proceeding further. Indeed, any module included in this list remains visible on the Extend-tab. As such, leaving an unused but incompatible module risks it inadvertently being installed at a later date: This could break your website.

Screenshot of the REMOVE tab.

 

The UPDATE tab displays modules with pending updates alongside their compatibility status.

If you have any modules listed under this tab, we recommend you to first complete the pending updates. In most cases, applying pending updates will ensure Drupal 9 compatibility. Updating already installed modules is done directly through the UI by heading to the Extend-tab and choosing the Update header.

The UPDATE tab.

 

While it may not be strictly necessary to update your modules to ensure Drupal 9 compatibility, it is generally good practice to keep your installed modules up-to-date as security updates and new features are regularly pushed. If you are uncomfortable updating modules, or face any problems doing so, please do not hesitate reaching out on the Drupal Community forums.

The SCAN tab shows the modules whose compatibility cannot immediately be determined.

Tick all relevant modules, scroll to the bottom of the page and click Scan selected.

The SCAN tab.

 

The Upgrade Status tool will then automatically scan the selected module(s) and inform you of what, if anything, needs to be done in order to ensure Drupal 9 compatibility. Since the Upgrade Status tool has access to all the files installed on your website, you can rest assured that if anything needs updating, it will be revealed by the scan. Similarly, if everything clears and nothing shows up following a scan, you can safely assume your site is already Drupal 9 compatible. Indeed, the official CERN themes and modules are already Drupal 9 compatible.

Example of Fixing a Module

Once the scan completes, a number of modules might be flagged as being incompatible, e.g.:

Result scan example.

 

Selecting either in the LOCAL SCAN RESULT-column yields a window similar to the below:

Local scan result specific.

 

The Upgrade Status will always identify what needs changing in order to ensure Drupal 9 compatibility. Specific files and lines in said files are highlighted. Additional information will also be available where applicable in the Error-column. In this particular case, the error reads: Add core_version_requirement: ^8 || ^9 to designate that the module is compatible with Drupal 9. This specific error is by and far the most common error; and fortunately also very easy to fix as it merely requires pasting a single line of code.

If you are seeing a different error you do not know how to resolve, let us know on the Drupal Community forums!

1. Connect to your website's WebDAV.

If you are unsure how to do this, check https://drupal-tools.web.cern.ch/access-webdav-in-openshift.

2. Click Modules.

WebDAV

3. Click Custom.

This is the only folder you should concern yourself with as it contains your installed and active custom modules.

Custom module

4. Find the relevant module you wish to make changes to. In this case, we proceed with the CERN Landing Page module.

Selecting module

5. Identify the specific file in need of updating as specified by the Upgrade Status report.

Finding file

6. Click the file to download it. Open it with any text editor.

Download and open file

7. As identified by the Upgrade Status tool, we need to add a single line of code to the .yml (.yaml) file.

Before edit

Paste the  core_version_requirement: ^8.8 || ^9 line as instructed.

You may post this line anywhere, e.g. immediately above the dependencies line.

If your file already contains a core_version_requirement line, simply ensure it says ^8.8 || 9.

If a core: 8.x line is present already, you may replace that in-place entirely with core_version_requirement: ^8.8 || ^9.

Pasted line

Note the difference in line 5. Save the file.

8. Return to the WebDAV window. Click Upload file(s) and browse to the file you just edited. Select this and upload. This will override the old version.

Upload changes

You can now re-scan the module in question and see it pass.

Rinse and repeat this process for all identified modules. Once done, you will have a screen similar to the below:

Upgrade-status

 

In the vast majority of cases, the specific ERROR will merely be updating the .yaml file as outlined at the beginning of this guide. If the error is different, please feel free to reach out on the Drupal Community forums and we will do our best to assist you.

If you have any custom PHP functions, these likely also require updating to ensure functionality remains intact in Drupal 9. If you are unsure whether this is the case, please await the OpenShift migration and utilise the included source code scanning feature. If you are using older versions of CERN-specific modules, please replace these with the newest releases found on Gitlab.

 

Kindly note that in some instances, a COLLABORATE WITH MAINTAINERS tab may also appear. This tab can safely be disregarded. However, if any module but the Webform module is displayed, please reach out on the Drupal Community forums as additional assistance is necessary.

You may also be interested to watch the recording of the Zoom workshop: Drupal 9 upgrade: How to check your website.

Questions or issues? Get in touch on the Drupal Community forums.