Backwards Compatibility vs Evolvability vs Maintainability

The benefits of backwards compatibility (BC) are clear: no users are left behind. Which leads to higher adoption rates because you’re often getting new features and you always have the latest security fixes.

Of course, that’s easy when you have a small API surface (as Nate Haug once said: “the WordPress API has like 11 functions!” — which is surprisingly close to the truth). But Drupal has an enormous API surface. In fact, it seems there’s APIs hiding in every crevice!

In my job at Acquia, I’ve been working almost exclusively on Drupal 8 core. In 2012–2013 I worked on authoring experience (in-place editing, CKEditor, and more). In 2014–2015, I worked on performance, cacheability, rendering and generally the stabilizing of Drupal 8. Drupal 8.0.0 shipped on November 19, 2015. And since then, I’ve spent most of my time on making Drupal 8 be truly API-first: improving the RESTful Web Services support that Drupal 8 ships with, and in the process also strengthening the JSON API & GraphQL contributed modules.

I’ve learned a lot about the impact of past decisions (by myself and others) on backwards compatibility. The benefit of backwards compatibility (BC). But the burden of ensuring BC can increase exponentially due to certain architectural decisions. I’ve been experiencing that first-hand, since I’m tasked with making Drupal 8’s REST support rock-solid, where I am seeing time and time again that “fixing bugs + improving DX” requires BC breaks. Tough decisions.

In Drupal 8, we have experience with some extremes:

1. the BigPipe & Dynamic Page Cache modules have no API, but build on top of other APIs: they provide functionality only, not APIs
2. the REST module has an API, and its functionality can be modified not just via that API, but also via other APIs

The first cannot break BC. The second requires scrutiny for every line of code modified to ensure we don’t break BC. For the second, the burden can easily outweigh the benefit, because how many sites actually are using this obscure edge case of the API?

---

We’ll look at:

• How can we make our modules more evolvable in the future? (Contrib & core, D8 & D9.)
• Ideas to improve this, and root cause hypotheses (for example, the fact that we have API cascades and not orthogonal APIs)

We should be thinking more actively about how feature X, configuration Y or API Z might get in the way of BC. I analyzed the architectural patterns in Drupal 8, and have some thoughts about how to do better. I don’t have all the answers. But what matters most is not answers, but a critical mindset going forward that is consciously considering BC implications for every patch that goes into Drupal 8! This session is only a starting point; we should continue discussing in the hallways, during dinner and of course: in the issue queues!

Preview: