Writing software is easy, sustaining it for years is harder, and doing it for open-source software is a challenge. Here’s a story about my journey to help build the WordPress block editor from a maintainer’s perspective, a perspective probably invisible to most developers and contributors (unless you’re an open-source project maintainer).

The fun part

As a long time developer, my main motivation is to ship features, write software, and put it in the hands of the users to help them achieve their goals. So when I heard about WordPress thinking about building a new editor from scratch, I immediately understood how impactful that project could be, given the scale of WordPress and the central place the editor occupies in any CMS. Thus, I volunteered very early on to join these efforts and was delighted to learn that I was part of a small team of people who were being sponsored to lend a hand there.

Starting a project from scratch is an opportunity most developers enjoy. The early days are where the fun happens: you get to define the structure, the guidelines of the project, the code style. You get to choose the technologies to be used and participate in the early prototypes. You define the base APIs and you get to engage in early design discussions. And more importantly, for a developer motivated by impact, you get to ship software at a very high pace. It is very rewarding.

And this is exactly what happened with the block editor project. Early on, we were a group of a dozen folks showing up on #core-editor weekly meetings, we worked on several prototypes, we created the base UI components ,we defined the desired base Block API and block-based format, and we eventually achieved an important milestone where the block editor could be shared with users and third-party developers as a beta version.

The growing part

The initial release of an open-source project is one of the most rewarding moments of the timeline. Early adopters get to enjoy your work, provide feedback you can act on. People start asking for features via issues and, with your existing knowledge of the project, your voice matters. Some of them can also provide their own contributions and open pull requests. Your feedback is important there since you have worked on the original APIs and architecture of the project. Eventually, you become an expert, a public figure, you get respected (or hated) for your work, but your input becomes necessary.

For the block editor project, there were a few of us in this situation and we were able to reasonably balance receiving feedback, acting on it, and making substantial improvements and iterations to the overall project.

At this point in time, you also start to be careful about public APIs. As any WordPress feature, the block editor is meant to be extensible at its core. Third-party developers can write custom blocks, and extend the editor in a number of ways. As we started getting more users for our plugin (beta product), and even if we were on a beta period in which API changes are allowed, we had to start thinking about being very explicit there. Identify and document the API changes, and ideally provide upgrade paths and time for third-party developers to adapt their code.

The serious part

Next up in the lifecycle of the software is to actually ship a stable version. It is very hard to know exactly where to draw the line and stop the iterations on the beta product and make the jump — but eventually the time comes, and with it comes the age of maturity. Your software starts to be used by a large number of users and extended by a number of developers (depending on the scale of your market/community).

In terms of software features, this is generally a small step, the software doesn’t change so much for its stable release. But in terms of flows and dynamics of the project, this is a huge turning point.

The first challenge you’ll face here is dealing with backward compatibility for all the APIs you have been building so far. The backward compatibility strategy differs from one project to another, but in general this means that you’re engaged to maintain these APIs working properly for a long time. You can’t risk breaking the user/developer’s trust.

For an NPM library (or any other developer dependency), you have the luxury to rely on semantic versioning. Meaning, making breaking changes to the API is allowed if you make sure to update the version of your software accordingly. This communicates your intent to your users. This is made possible because updating a dependency is an explicit action that a developer takes on its development environment, and thus the developer can make sure their extension/product still works with the new version before pushing an update to the production environment. Nonetheless, library authors try to avoid breaking changes as much as they can or at least reduce their frequency. The React team for instance only releases an incompatible version every couple of years or so, and when they do they make sure to provide a simple upgrade path for their users.

For WordPress, the story is very different. While WordPress does make some small breaking changes from time to time, its goal is to do none. This is understandable because updating WordPress is an operation users perform on their production websites. These updates can also be done automatically without any manual intervention. And with the scale of WordPress (38% of the websites at the time of writing), it can’t afford to break millions of websites because of a change incompatible with third-party plugins. 

So when the block editor landed as stable in WordPress 5.0, we knew we were making strong commitments towards supporting its APIs for a long time and this had a non-negligible impact on the development pace. It is very hard to quantify exactly but, for every pull request, a very careful review is required to check the impact on existing sites and APIs. This can also mean intentionally delaying features and enhancements until there’s a better moment/way to introduce the API changes with the minimum impact on existing sites and plugins. Spreading changes across different releases is a common strategy to help communicate changes and give time to third-party developers to adapt their code before actually making the required changes. As an example, it is no surprise that WordPress still uses jQuery 1, but it’s important to understand that a migration process throughout several major releases is underway.

While the impact of the backwards compatibility strategy on the development process and pace was something we anticipated properly, what came as a surprise to me was another consequence of the stable release: we put the software in the hands of millions of users while the size of the group that was referred to as the “experts” of the project remained unchanged. This led to a very high influx of notifications, direct messages, mentions on issues, pull request reviews, requests to discuss technical discussions and feature proposals. We became the bottleneck.

I’ve been reading a little bit about the subject (I strongly recommend these two posts: The city guide to open source by Devon Zuegel and (Open) source of anxiety by Henry Zhu) and this seems to be a common problem in successful open source projects: the people most equipped to move the project forward by undertaking big changes and improvements are the less likely to have time to actually make these changes.

What’s next

This is the current challenge we’re being faced with. How to make sure we help the community as much as we can and move the big upcoming projects forward: full site editing, widgets screen, navigation block, global styles — just to name a few.

WordPress has an amazing community. More contributors are embracing the vision and gaining expertise. I’m confident that, with the participation of all, we’ll make it happen and climb another step in our journey to democratize publishing.