Co-contribution with clients: A revision UI API for all entity types

by lee.rowlands /

Share this post on social media

The tale of an eight-year, collaborative effort to build a generic revision UI into Drupal 10.1.0, bringing a major piece of functionality to core.

As we discussed in our previous post, Improving Drupal with the help of your clients, we’re fortunate to work with a client like ServiceNSW that is committed to open-source contribution. So when their challenges require solutions that will also benefit the whole Drupal community, they're on board!

In the beginning, there were nodes

Since Drupal 4.7 was released in 2006, nodes have had a revision user interface (UI). The UI allows editors to view revision history and specific revisions, as well as revert and delete revisions.

A lot has changed since Drupal 4.7. We received revision support for many more entities, but Node remained the only one with a revision UI in core.

Supporting client needs through contrib 

Our client, Service NSW, makes heavy use of block content entities for Notices displayed throughout the site. These are regularly updated. Editors need to be able to see what has changed and when, revert to previous versions, and view revision logs when needed. 

Since Drupal 8, much of the special treatment of Node entities has been replaced with generic Entity API functionality. Nodes were no longer the only tool in the content-modelling toolbox, with this one exception: revision UI.

The code for node's revision UI lives in the node module. It’s dependent on hard-coded permission checking and uses routing and forms outside the entity API.

This meant that for every additional entity type for which Service NSW needed a revision UI, those parts needed to be recreated repeatedly.

As you can imagine, this approach quickly becomes hard to maintain due to the amount of duplication. 

The journey to core

Having identified that Drupal core needed a generic entity revision UI API (it already had generic APIs for entity routing, editing, viewing and access), we set to work on this missing piece of the puzzle.

We found an existing core issue for it, and in 2015, posted our first patch for it. 

This began an 8-year journey to bring a major piece of functionality to core.

Over the course of many re-rolls, we released contributed modules built on top of the patch:

Finally, with the release of Drupal 10.1.0 in 2023, any entity-type could opt into a revision UI. The Drupal 10.1.0 release opted-in for Block Content entities, making that contributed module obsolete. Then later in 2023, the release of Drupal 10.2.0 saw Media entities use this new API. In early 2024, support for Taxonomy terms was added and released in 10.3.0.

Challenges along the way

The biggest challenges encountered were keeping the patch up to date with core as it changed and navigating the contribution process. Over the years, there have been over 120 patch files and 300+ comments on the issue!

Another challenge was the lack of an access API for checking access to revisions. 

The entity API supported a set of entity access operations — view, update, delete — but no revision operations were considered. The node module had hard-coded permissions e.g. 'view all revisions' and 'revert all revisions'. 

To have a generic entity revision UI API, we needed a generic way to check access to the operations the UI would make available.

Initially, we tried to include this with the revision UI changes. However, it became increasingly difficult to get both major pieces of functionality simultaneously. So, in 2019, this was split into a separate issue, and the original issue was postponed.

With efforts from our team, Service NSW and many other individuals and companies in the Drupal community, this made it into Drupal core in 2021. It was first available in Drupal 9.3.0. Adding a whole new major access API is not without its challenges, though. Unfortunately, this change resulted in a security release shortly after 9.3.0 came out. Luckily it was caught and fixed before many sites had updated to 9.3.0.

Collaborative contribution

Adding a new feature to Drupal core is a large undertaking. Doing it in a client-agency collaboration provides an ideal model for how open source should work. 

Developers from PreviousNext and Service NSW worked with the broader Drupal community to bring this feature to fruition.

Our developers have experience contributing to core and were able to guide Service NSW developers through the process. Being credited on large features like this is a major feather in the cap for both individual developers and their organisations.

Wrapping up

Together, we helped integrate a generic revision UI into Drupal 10.1.0. All of the developers involved received issue credits for their work. 

This was a significant effort over eight years, requiring collaboration with individuals and organisations in the wider Drupal community to build consensus. This level of shared commitment helps drive the Drupal open source project forward, recognising that what benefits one can benefit all.

So, what are the next big features you and your clients could work on? Or is there something you want to bring to core, as an individual, group or organisation? Either way, we’d love to chat and collaborate!

Contributors

  • dpi
  • acbramley
  • jibran
  • manuel garcia
  • chr.fritsch
  • AaronMcHale
  • Nono95230
  • capysara
  • darvanen
  • ravi.shankar
  • Spokje
  • thhafner
  • larowlan
  • smustgrave
  • mstrelan
  • mikestar5
  • andregp
  • joachim
  • nterbogt
  • shubhangi1995
  • catch
  • mkalkbrenner
  • Berdir
  • Sam152
  • Xano

Related Articles