The tech behind Drupal's Project Update Bot

Drupal.org's Project Update Bot was originally built for the Drupal 8 to 9 upgrade and is now running again helping maintainers to make drupal.org projects compatible with Drupal 10 as well. It automatically opens issues in drupal.org projects' issue queues when there is a Drupal 10 incompatibility identified, and provides a best effort fix as well. Then project maintainers and users can further refine the fix and include it in the project at their own timeframe. But what's behind the curtain? How does it work?

Underlying tools

The first key component that enabled this automation is phpstan-drupal created by Matt Glaman originally at Centarro for code quality checking. This integrates Ondrej Mirtes' PHPStan for static Drupal code analysis. While phpstan is now used for Drupal core code quality checking as well, it had a sizable detour when we realized finding uses of deprecated APIs would be made much easier with it. That is where Matt Glaman created drupal-check and Acquia created the open source Upgrade Status UI on top of it that expanded on the functionality considerably as well (checking deprecated Twig markup, Drupal libraries, info files, etc).

But finding the uses of deprecated APIs is only part of the solution. Fixing them automatically is much better. This is where Palantir.net picked up the drupal-rector project originally prototyped by Pronovix. Drupal-rector, based on the Rector project by Tomas Votruba was then heavily updated and expanded to cover the majority of Drupal 8 to 9 deprecated APIs with automated fixes. And in the Drupal 9 to 10 process, Palantir.net funded even higher coverage of deprecated APIs. Now only a few percentages of all deprecated API uses found in all drupal.org contributed projects is left uncovered.

So now that we can detect the problems and fix most of them, how can we automate that further? That is where the idea of the Project Update Bot came in. Built by Ted Bowman at Acquia's Drupal Acceleration Team in collaboration with the Drupal Association, it combines the above tools brilliantly. The Drupal 10 compatibility update of the bot itself was led by Björn Brala at SWIS, who keeps working on stability improvements.

Bot logic

Project Update Bot is executed as part of the weekly job running at the Drupal Association, which provides the data for the Deprecation Status Dashboard as well. The patch generation portion is open source in the Drupal.org Infrastructure repository. Here is how it works:

1. Upgrade Status is run on each Drupal 9 compatible drupal.org project. For some of them, it runs on multiple branches. The latest and most used ones are attempted to be picked on a best effort basis.
2. If Upgrade Status reported no deprecated API uses, the project will not receive a bot patch. Otherwise drupal-rector is run on the codebase to attempt to fix the issues.
3. After that, Upgrade Status is run again to see if drupal-rector fixed all the problems. If all problems were resolved other than info.yml files and composer.json core version metadata, those also get updated for Drupal 10 compatibility. The lowest compatible version is possibly updated based on the detected version of removed deprecated APIs.
4. Finally the patch is posted into the existing bot issue or if no issue yet, a new issue is opened.

While the deprecated API detection and fixes are produced the best way we can, there is no guarantee that all of the deprecated API uses are identified or even fixed. So it is after all still up to humans to review and refine the patches posted. All the Project Update Bot does is to provide a head start with making it happen, so most of the repetitive parts of the process are automated. All posted issues contain instructions as to how to interact with the bot to stop further patches being posted or keep receiving updates.

Drupal 10 compatibility results after the first month

Drupal 10 compatibility patches were first posted starting June 14, 2022 with two updates since then. Altogether 6350 issues were opened. At the time of this writing, 4% of them are already closed as fixed or ready to be committed, while 2% of them are closed in another way, such as duplicates of existing efforts.

42% of the top hundred projects are Drupal 10 compatible already, while the beta version of Drupal 10 itself is not even out yet. I think the Project Update Bot contributed a lot to that directly and indirectly.

Let's start reviewing and refining the fixes!

Next Friday is the first Drupal 10 Global Porting Day on July 28/29, which provides a good opportunity to use the patches as a starting point and see if we can get more projects Drupal 10 compatible on time! Hope to see you there!