This time it’s different. We promise.
Before we can talk about Drupal 9, we have to talk about Drupal 8. It’s been a minute since Drupal 8 was released—way back in 2015! Back then we didn’t know Facebook was the problem, Game of Thrones was still great, and David Bowie had not yet left on his Space Oddity.
Looking back, Drupal 8 was not an easy birth. Rather than an upgrade, D8 became a rewrite of the Drupal platform, breaking most APIs and rendering all Drupal 7 contributed modules incompatible with the new framework. An upgrade to Drupal 8 required major rewrites of both contributed modules and custom code on existing Drupal 7 sites. The practical effect was that going from Drupal 7 to Drupal 8 was nearly as much effort as rebuilding a site from scratch.
This was not a new issue in Drupal 8. Looking back to Drupal 6, a massive rewrite of Views for Drupal 7 delayed the stable release of this critical module from being ready until many months after Drupal 7’s launch. Though many forget now, this slowed Drupal 7’s adoption rate. The good news is that the lessons of history have been learned.
Fast forward to today and the plans for Drupal 9 are far different. The release of Drupal 8 was all about paying down technical debt so that future releases would be like they are in WordPress: painless, fast, and fun. With Drupal 9, that vision has been realized. Assuming your Drupal 8 site follows best practices and you adhere to this readiness guide, an upgrade to Drupal 9 should be a modest level of effort, measured in hours and days, not weeks and months.
The purpose of this guide is to be a one stop shop on how to ensure that a new or existing Drupal 8 site is set up for a successful, easy Drupal 9 upgrade. This represents the collected wisdom of our sought after Drupal practitioners and architects and our resident Drupal core maintainer, @catch.
Start reading or jump ahead here.
Major Differences between Drupal 8 and 9
You can expect three major changes in Drupal 9.
Deprecated Code. The first major change is that Drupal 9 removes support for a whole bunch of code that was marked as deprecated in Drupal 8. You can think of Drupal 9 as a major spring cleaning release, where code is being removed that exists today in Drupal 8, but that the core maintainers have made clear should not be used anymore. Removing this code in Drupal 9 means that test coverage is easier and increases Drupal 9’s freedom to maneuver by making the code more nimble.
🛑 Watch out for this one: The main deprecated code that will be an issue for some projects is tests depending on Simpletest, although there might be mitigations (like a contributed module, or it being removed in Drupal 10.) Skip ahead to our tips on handling deprecated code.
D9 modules can work on D8 sites (single codebase!). The second major change in Drupal 9 is that it might be possible to maintain a single codebase for a contributed module and have it work in both Drupal 8 and Drupal 9. This would be a first in Drupal. While the plan hasn’t been finalized, it appears that a leading option for Drupal 9 will allow a contributed module to list more than one core version of Drupal as a requirement in it’s module infoYAML file. This represents a paradigm shift in Drupal from upgrades being breaking, major events to the mature stability of upgrades being steady, even, manageable progress.
The third major change in Drupal 9 is that the major versions of Symfony and Twig are changing. Drupal 9 will ship with either Symfony 4 or 5, and with version 2.0 of Twig. These are both major upgrades for core Drupal components, so it’s great news for Drupal to benefit from the security, performance, and developer experience improvements in both. Along these lines we should also expect the PHP requirements to increase in Drupal 7 to PHP 7.2, 7.3, or possibly 7.4.
Nothing too crazy, right? The big news about Drupal 9 is that there isn’t any big news, and that is very much a good thing.
The Drupal 9 Timeline
These are the important dates to keep fresh in your mind.
-
June 2020: Drupal 9 releases
-
November 2021: Drupal 7 AND Drupal 8 reach end-of-life. This is just under a year and a half after D9 releases.
Here’s the important note: it doesn’t matter if you’re on D7 or D8, you should start the upgrade process as soon as D9 releases in June 2020.
-
If you’re on D8: As long as all the code in your Drupal 8 codebase doesn’t contain deprecated code, you can upgrade anytime after Drupal 9 is released. Why not just knock it out and be done with it?
-
If you’re on D7 still: Go for it, upgrade from D7 → D9. All of the Drupal 7 migration paths will remain in Drupal at least until version 10, and going from Drupal 7 to 9 won’t really be any harder than going right to Drupal 8 (so long as you follow our guidelines here). Here’s how we approach the D7 → D8 upgrade for our clients.
Drupal 8 will stop getting new features the day Drupal 9 is released. This means that once Drupal 9 is production ready, Drupal 8 will only get security and critical patches. Why is this important? If you want to stay current with the latest and greatest features in Drupal you are going to need to upgrade to Drupal 9 as quickly as possible.
What the Drupal 9 Upgrade Path Looks Like
Updating from Drupal 8 to Drupal 9 is going to be much easier than it has been in the past. The entire process should be similar to upgrading a minor version of Drupal 8 (such as from 8.6 to 8.7). The most important factor when preparing for the upgrade is making sure you regularly check for and remove deprecated code. Each minor version of Drupal 8 deprecates code that will no longer be supported when you make the upgrade to Drupal 9. As long as your Drupal 8 website is not using deprecated code, the upgrade will go smoothly.
For an existing Drupal 8 site:
-
Perform an audit of all of your custom modules and prepare an inventory of all of the deprecated code that is used. Use a tool like drupal-check to perform this inventory.
-
Either work through and remove all deprecated code in one fell swoop or track the inventory with your project documentation and make a plan to, say, address the deprecations every time you touch nearby code. Skip to our tips on handling deprecated code.
For a new Drupal 8 site:
-
Familiarize yourself with documentation and make sure that the entire engineering team is clear to avoid their use on all custom code written.
-
Use a tool like drupal-check near the end of the development phase to make sure no deprecations in custom modules snuck through. Skip to our tips on handling deprecated code.
The State of Contributed Modules
The major contributing factor that caused the delay in Drupal 8 adoption after it was released was that so many contributed modules in Drupal 7 were not upgraded to Drupal 8. Without a stable D8 release, many organizations simply waited for their modules to be ready.
The good news is that as of an analysis completed in April, nearly half of all Drupal 8 modules are essentially fully compatible with Drupal 9 (a tiny change to the .yml file will be required, but that is it). The other half do require code changes to work with Drupal 9, but for the majority of those there are three or less changes needed. In short, unlike in Drupal 8, contrib will be ready on the day Drupal 9 is released.
Gábor Hojtsy has done an outstanding analysis of the state of contributed modules for Drupal 9 readiness that is worth reviewing in detail.
Technical Tips for Getting Ready for Drupal 9
We’re hooking you up with some juicy tips from our sought after architects and our Drupal core maintainer (yes, we employ and sponsor @catch who works on Drupal 8 and 9). You can trust us with these tips because we are helping to plan, architect, and code Drupal 9.
Tip #1: Keep your Drupal site updated
Probably the most important aspect of preparing for D9 is staying current on the latest version of D8. The first release of D9 will be based entirely on the last release of Drupal 8. In addition to keeping the core Drupal system updated, staying current on module updates will help ensure continuing compatibility as they update in preparation for D9.
If you keep your modules updated on your Drupal 8 site, you should find that most of the contributed modules you use will be ready to go by the time Drupal 9 is released.
Tip #2: Deal with deprecated code
If any of your custom modules or themes are using deprecated code, make a plan to start updating these during your next site release schedule. This way you are staying ahead and will save yourself additional time in the future. If you are planning to add additional features to your site, make sure your developers are not using any deprecated code. Periodically checking your code with the upgrade status module (mentioned below) is a great way to ensure you stay as ready as possible. Most of the Drupal 9 code that is deprecated has instructions in the Drupal API documentation on how to update the existing code to use the recommended approach.
The Upgrade Status module provides a user interface that checks the contributed and custom projects on your site to determine if they contain any deprecated code.
You can also use automated deprecation tracking and static analysis tools to detect and repair custom code using deprecated APIs. Subsequent D9 releases will remove many of the APIs currently deprecated in D8. Stand alone SA tools are available for this task.
Tip #3: Periodically review the proposed changes in core module removals
Track ongoing issue of core module removals / merges as they are decided. Determine if custom implementations will require functional or configuration updates for core changes. Here's the current D.org issue.
Tip #4: Use "mostly-stable" beta core functionality for new site builds
Although the roadmap for merging stable versions of layout / bricks, media gallery and other current beta functionality isn’t fully clear, new site builds will probably avoid more extensive upgrade / content refactoring operations later if built using beta / future core modules.
Tip #5: Report code deprecation warnings for contributed projects
If you want to be especially proactive in your preparation for Drupal 9, you can help contributed module maintainers. Simply reporting the deprecated code warning in the issue queue on the project page on Drupal.org is the first step in the process. How do you think contributed modules get updated, anyway? 😉
You should always double check there is not already an issue created before submitting. You can go one step further by making the code change, testing it, and submitting patches to the contributed projects you are using that have deprecated code. Or just reviewing and testing existing patches and updating the issue queue.
Tip #6: Make sure you are using actively maintained modules
Are all the contributed modules and themes you use still actively supported by their maintainers and with stable Drupal 8 releases? If not, check the project issue queue to see what the status is. Modules that aren't being actively maintained during the Drupal 8 cycle are the biggest risk to being able to move to Drupal 9, so you may want to look for alternatives or offer to help with maintenance.
Tip #7: Make sure you have test coverage
Do your custom modules have test coverage? If so, make sure everything is testing with phpunit (SimpleTest is deprecated!) and you have no group @legacy tests. And ensure that deprecation messages cause a test failure (i.e. if running tests with run-tests.sh make sure you're not using the --suppress-deprecations flag)
Tip #8: Consider testing the alphas
Drupal core will release Drupal 8.8.0-alpha1 on October 14, 2019. Consider testing the alpha and beta releases, or even joining the official beta testing program in order to catch any upgrade bugs early. The Drupal 9 upgrade will include all the changes in Drupal 8.8 and Drupal 8.9 too, so making each step as small and reliable as possible helps the overall migration. Some time after Drupal 9 is branched, there will be tagged alpha and beta releases to test against too.
Tip #9: Embrace Composer
Are you already building your sites with Composer? If not, consider switching over while you're still on Drupal 8. Composer is the leading, de facto package management tool for PHP, and the established best practice. If you want to be a better developer, you have to commit yourself to established best practices, and Composer is an important one.
Tip #10: Don’t use Panelizer
It is not entirely clear yet if this will happen, or exactly how, but Panelizer is likely on its way out. What is likely is that this contributed module will be replaced by the new Layout Builder, which is in core. Given the momentum behind Layouts (Panelizer is being ripped out of Lightning) and the uncertainty behind Panelizer’s fate, it is probably wise to avoid using this module on any new efforts.
Tip #11: Don’t use contributed versions modules that have gone into core as alpha or beta in Drupal 8
The Migrate, Workspaces, Layout, Field Layout, and Media Library contributed modules have all been brought into Drupal 8 core either in an alpha or beta state. As these modules will be in Drupal 9 core fully supported, ensure that you move away from these modules in your contrib library and switch to the core versions.
Tip #12: Brush up on Symfony and Composer
Drupal 8 introduced the popular PHP web framework Symfony into the core of Drupal, and added support for PHP’s powerful package manager Composer. Drupal 9 will build on these investments and lean even more heavily on these two awesome technologies. If you aren’t fluent in these tools yet, then Drupal 9 is going to be more of a challenge for you. Spend some time upping your skills in this area and you will be more ready for the upgrade.
Bonus: mastering these two frameworks will make you a better engineer.
Tip #13: Check your site with Symfony 4 (Advanced & adventurous users only)
Drupal 9 is going to use Symfony 4, so it can be handy to perform a quick experiment to see how your Drupal 8 site will behave. It is still early days for Symfony 4 support, but one idea for readiness is to create a quick dev branch in Git, drop in Symfony 4, and see where the rough edges are. It’s probably too early to spend much time addressing the issues, but this can help identify if you have any large chunks of code that are going to need attention for compatibility.
Tip #14: Try the upgrade path (Advanced & adventurous users only)
This is an alpha strategy not yet available but here we go: Soon (in the next few weeks or months) a new branch will be created on Drupal.org for Drupal 9. Try the upgrade path on this branch on your own site to see if there are any unexpected issues not documented here. This will shed light on what should really keep any technologist up at night: the unknown unknowns.
Dealing with Drupal 7?
The jump from Drupal 7 to 9 is complex and requires thoughtful planning, but only because the move from Drupal 7 to 8 takes work. Once you are on 8 the move to 9 is relatively modest. Going step by step will end up saving time in the long run.
Seriously, read our guide on deciding to upgrade to Drupal 8 or skip straight to Drupal 9.
Wait, You’re Still on Drupal 6?!?!?
At the time of this writing, there are still 50,000 Drupal 6 sites phoning home. It’s crazy to think, but they are still out there. One important note for anyone still on D6: Drupal 9 will drop support for a migration path from Drupal 6 meaning this code will be removed from Drupal core and live in a contributed module. But still, without core support this migration path is unlikely to be as well supported so the release of Drupal 9 should serve as extra motivation—beyond that pesky lack of security patches—to upgrade these sites.
Bottom line: While someone in the community might decide to support the Drupal 6 upgrade path, you should operate from the perspective that migrating to a future version of Drupal from D6 is going to be exceptionally harder. And don’t forget that if you get any level of traffic to your D6 site, it isn’t if, but when, your site will be compromised. You should upgrade to Drupal 8 (and then Drupal 9) as quickly as possible.
What About Drupal 10?
The adoption of the Symfony framework in Drupal core was one of the fundamental changes in Drupal 8, driven by a goal to reduce writing code that already exists (and reaping the benefits of battle tested code). The practical effect of this marriage between Drupal and Symfony is that inevitably the release cycle and major version of Symfony impacts the release schedule of Drupal (this will be the main driver behind when Drupal 10 will be released.)
The crucial factor is that Drupal 9 will either release with Symfony 4 or 5. Symfony has a well defined release and support schedule: Symfony 5 will be released this November and be supported until November 2025. Symfony 6 will be released in November 2021 and be supported until November 2027. The Drupal core maintainers will want to release Drupal 10 around 2022 or 2023, more than two years after D9 but no more than three. What this all means is that the Symfony version at the heart of Drupal 9 will go out of support in either November 2023 or November 2025, and that dictates when organizations must move to Drupal 10.
The best news is that as with Drupal 9, the upgrade to Drupal 10 will be a similarly modest level of effort, if a site stays updated and follows best practices. And, with the release cycle of Drupal becoming more narrow and predictable, IT organizations can finally plan ahead in terms of budgets and time investment to update this crucial part of their technology infrastructure.
How to contribute to Drupal 9
The best way for your engineering team to get acquainted with Drupal 9 is to help finish this new version of Drupal. Consider allocating time for your engineers in your next Drupal project to upgrade a contributed module or piece of Drupal core to be compatible with Drupal 9. This will involve a meaningful contribution back to the open source platform and start the process of knowledge transfer from the core Drupal 9 team and your engineers that will be necessary for your team to be able to support your site.
More reading
Did we not give you enough Drupal 9 goodness? Let us know what we need to add and check out these pieces in the meantime.