What you should know before upgrading to Drupal 8.3

Don’t panic! If you don’t use Content Moderation- and Layout Plugin-based components (like Display Suite, Panels, Panelizer and Contexts) then you’ll be fine upgrading to Drupal 8.3. If you do, there are just a few things you need to know first.

“It looks insanely complicated, and this is one of the reasons why the snug plastic cover it fitted into has the words Don’t Panic printed on it in large friendly letters.” – The Hitchhiker’s Guide to the Galaxy

One of our Drupal 8 projects relies on the core experimental module Content Moderation. The module has been partially re-written with Drupal 8.3, becoming dependent on the new core experimental module Workflows, so we decided to put some effort into updating to this latest minor version and studying all the changes.

An initial upgrade path workflow

We’ve been aware of Content Moderation changes for a while, thanks to the change record “Experimental Workflows module added to core”, circulating since the beginning of the year. The section on “Important upgrade information” was as scary as it was useful: “you will need to uninstall it before updating the codebase and re-install after”. And of course, “as this is an ALPHA experimental module data upgrade paths are not supported”.
(UPDATE: there is an unofficial upgrade path. I agree with Tim Millwood’s comment: “worth a try if stuck”.)

We decided to experiment with what the best upgrade path would have been for our scenario, and came up with a pretty strong workflow:

• Put website in maintenance mode.
• Approve/Reject all the content waiting for approval. The only allowed states are Published or Draft/Unpublished. This is because after uninstalling Content Moderation, Published and Unpublished are the only states Drupal will recognise.
• Delete content_moderation_state entities (/admin/modules/uninstall/entity/content_moderation_state).
• Uninstall Content Moderation and dependencies, if any.
• Upgrade Drupal codebase to 8.3 latest version.
• Run database updates.
• Re-install Content Moderation and dependents, if any.
• Re-create the moderation States and Transitions from the new Workflow based UI. If you use the same name machines, you probably don’t need to update any of your custom code or views.
• Restore the website, disabling Maintenance Mode.

After doing this, you check some random pages… and you notice something is wrong.

What’s the problem?

Visiting one of your content types’ custom display modes, made with Display Suite, may show you some fields have been disabled (they’ve either been moved to the Disabled region, or they’re missing altogether)!

Or you may notice your custom Layout theme suggestions are not loaded for your Panels.
Shame on you. You haven’t read the other 8.3 Change Records, nor the full 8.3.0 release notes.

Layouts, layouts everywhere…

The Layout Plugin contrib modules, used by modules like Display Suite and Panels, has been dropped. Instead, we have the Layout subsystem and a new experimental module, Layout Discovery, in core.

The reason for this is to unify the way contrib and custom modules (and themes) can define their own layouts, and enable them to reuse layouts created with all the modules implementing the Layout API. Putting it in core is an incentive for doing it once and doing it well.

Both Display Suite and Panels suggest using brand new branches with Drupal 8.3 (as now they both make use of the new Layout subsystem). Though apparently, you could still use your original versions, with a bit of custom effort/code. It doesn’t work for me no matter what I do, as most of the fields are still missing on my display modes which are managed through a Display Suite layout.

Let’s update those modules

Display Suite needs to be updated to version 3.0 or higher, Panels and Page Manager to 4.0 or higher. Running database updates will uninstall Layout Plugin contrib and install the Layout Discovery core module replacement, enabling the new Layout subsystem.

The Display Suite issues queue is full of people experiencing problems at this point of the process. Missing Fields, Fields in the wrong regions or Disabled, Fields settings reverted to default values. The guys are doing a wonderful job of trying to fix the bugs, and explain the best solutions for a full recovery.

DS 3.0-beta3 contains most of these fixes, and restored most of my fields and settings.

You’ll still need to review ALL your form and view display modes, because here or there, there could still be glitches.

In my scenario, I have six content types and around four custom display modes for each, so it took me around an hour to re-configure all the fields in the right way. For this reason, I do suggest going through this review process in a staging environment, before exporting the configuration and re-importing it in Production. Much quicker and safer.

Dude, where’s my layout?

You may notice that something still looks weird on a Panel or when viewing content. You think it might be related to the template, and then you remember that that specific node type or page uses a custom template, through a template suggestion.

The file is there, twig debug tells you the suggestion is on the list and so should be considered, but the file is not loaded. This is a bug (and there is already an issue for it).

Layouts used in Display Suite displays should not be affected by this bug as long as, when you define the layout on your mytheme.layouts.yml, you set the class property to ‘\Drupal\ds\Plugin\DsLayout’.

i.e.

custom_1col_hero:
  label: Custom one column layout with hero (fixed)
  category: Custom
  template: templates/layouts/custom-1col-hero
  class: '\Drupal\ds\Plugin\DsLayout'
  regions:
    hero:
      label: Hero
    main:
      label: Main
    footer:
      label: Footer

This is a workaround made for and by Display Suite. For websites using any other Layout-based contrib modules like Panels, there’s currently no solution, other than patching the core codebase.

Conclusion

The big lesson here is about contrib modules: updating core to the new version is a requirement for developers and site-builders. But forcing websites to use the unstable branches or experimental modules is as problematic as it is dangerous. Unstable code is, by definition, unstable, possibly unsecure and isn’t easy to update.

Implementing new features and surfing the new trends is essential for staying relevant. But to do that, site owners should really be given the option of choosing between stable and experimental modules.

Here are some useful links to more info:

• [plan] Add layouts to Drupal: https://www.drupal.org/node/2811175
• Layout plugin documentation: https://www.drupal.org/node/2619128
• How to upgrade from Layout Plugin: https://www.drupal.org/docs/8/api/layout-api/how-to-upgrade-from-layout-plugin
• Does Drupal have a minor upgrade problem? http://www.aleksip.net/does-drupal-have-a-minor-upgrade-problem