We use cookies to offer you a better browsing experience, analyze site traffic, personalize content, and serve targeted advertisements. Read about how we use cookies and how you can control them by clicking "Cookie Settings." If you continue to use this site, you consent to our use of cookies.

Privacy Preference Center

Acquia’s websites may request cookies to be set on your device. We use cookies to enrich and personalize your user experience. Cookies help us know when you visit our websites, how you interact with us, and what content you view, so we can customize your experience with Acquia, including offering you more relevant content and advertising. You can also change your cookie preferences. Note, that blocking some types of cookies may impact your experience on our websites and the services we are able to offer.

Essential Website Cookies:
These cookies are strictly necessary to provide you with services available through our websites and to use some of its features (such as access to secure areas). Since these cookies are strictly necessary to deliver the websites, you cannot refuse them without impacting your experience and how our websites function. You can block or delete them by changing your browser settings, as described under the heading "How can I control cookies?" in the Cookie Policy.

Non-Essential Website Cookies:
These cookies collect information that is used to help us understand how our websites are being used, how effective our marketing campaigns are, or to help us customize our websites and applications to enhance your experience. You can click below to remove these cookies from your website experience. However, without these cookies, certain functionality may become unavailable or unusable.

How to track and remove deprecated Drupal APIs from your codebase

Drupal 9 is scheduled to be released on June 3, 2020. What this means to you has been extensively covered in the Driesnote at DrupalCon Amsterdam 2019. Now, how do you go about actually getting the job done and removing deprecated APIs from contributed modules you’re using? There are several tips I’d like to share here. Nothing breathtaking, but rather a systematic approach to ensuring you’ll stay on top of things so your apps are ready on the day of the Drupal 9 release.

Before we get started, here are a few resources you might find useful:

Planning ahead

The challenge in front of you is not technical as most API changes involve only a few lines of code. Rather, your mission is to start planning ahead now. As of the writing of this blog post, you have about 7 months to be ready. This might seem like a lot, but there are several factors to take into account:

Consider the time it’s going to take for maintainers to look at a given patch, provide feedback, get the patch committed and a new stable release tagged. Multiply this by N patches in M contributed modules.

Consider how many cycles your development team will be able to allocate in upcoming sprints, when conflicting forces are at play and your immediate need is to successfully ship new projects for your customers or colleagues.

To get organized, I’d suggest you leverage your issue tracker of choice and write down bite-sized chunks of work you can easily slide into sprints. Here’s an example :

Here, I’m using a Jira EPIC called ‘Prep for Drupal 9’ which is meant to track one issue per custom or contributed module I know is using deprecated APIs. Your strategy might be different whether you maintain only one app or many and you want to abstract out popular contrib modules in their own EPIC because they have the potential to impact most/all apps you’re responsible for. The reason why I insist on breaking things down into dedicated issues is not all contrib modules are created equal and will be ready at the same time. As we split up the work into chunks, we can then make decisions based on information at hand around the day of the Drupal 9 release. Those decisions can be formulated like so:

Is the module I need ready for Drupal 9?

Does the module I need have a stable release with deprecated APIs removed?

Can I afford to upgrade to Drupal 9 later, when this module is ready?

Can I afford to stop using this module temporarily/permanently?

Which strategy should I employ so I’m not limited by external circumstances? (more on that below)

There are times when you are blocked from removing APIs that are dependent on a minor version EOL or an upcoming minor release. This is the case of Facets and Google Analytics in the above example and it needs you to carefully think about the implications. As an example, if you maintain a contrib module and you remove an API that was deprecated in 8.8.x but your user base might still be running on a previous Drupal core minor version that is still being maintained by the Drupal Security Team, then you risk breaking their apps. As a responsible module maintainer, you should do the right thing, but only at the right time.

How to interact with the Drupal community

It’s easy to think about what you have to do, but it’s not so easy to determine how you’re going to do it. Let’s step back to understand what your next step should be when interacting with the community. Here’s a flowchart I came up with. I’ll explain the top-right composer.json patching circle in a moment.

You can see above I’m not using the Upgrade Status module but a CLI alternative called Drupal Check. It’s a customized runner for PHPStan which allows you to conveniently check Drupal deprecation rules. It’s also the perfect companion for your CI/CD integration. Check it out.

Tracking progress

A typical way to track progress for individual issues is to mimic how you’d work in the public Drupal issue queue. Post comments to keep the team in the loop about your work, and often update the issue summary for those who can’t afford to read many comments. Do note that in the screenshot below there’s a caption indicating when the check was last performed, which is always convenient to know about.

You should always keep in mind it's critical to track your work on drupal.org as this makes it possible for others to get involved. That being said, for your own tracker, another useful thing to do is to link to drupal.org issues so you always know what remains to be done for a module to be ready for Drupal 9 without leaving your workspace.

Did you notice that the linked Jira issues are rendered like issues on drupal.org? This is thanks to the Drupal Issue Chrome extension which greatly improves the UX on non-drupal.org pages and doesn’t force you into clicking on the links to see if there was any status change to any of the linked issues.

Finally, here’s a typical comments section. Remember you’re not posting comments for yourself but for others (or your future self) to see the detailed history, should you have to come back to this at some point in the future. It’s like writing a good Git commit message, right?

It’s time to switch to a Composer-managed install

If you’re still not managing your site via Composer, do it now. I can’t stress this enough. There are multiple ways to help you switch to a Composer-managed install (composerize-drupal, Composerize, drupal composerize’s Drupal Console command...) and there’s even a core issue that is discussing ways to help you safely do it with a community-approved solution. Note that at this point the community seems to be leaning towards leveraging composerize-drupal.

If you’re still not convinced, here’s one more reason: when it comes to removing deprecated APIs, sometimes things will be outside your control and it’s not a great feeling to be blocked by others. Remember the above flowchart and the top-right composer.json patching circle? This is my opinionated way to think about putting you back in control: while you might file an issue, post or review a patch, beg the maintainer to commit it and hope for a new release to be tagged ASAP, sometimes expectations won’t be met and you’ll need Composer to help you out.

Composer is a fantastic asset. Out of the many great things it does, it can be extended to safely patch your application without hacking core. And we’re going to leverage this opportunity with deprecated APIs. Here’s an example where we’re updating composer.json to include several patches from drupal.org: