How to deal with breaking backwards compatibility

While developing a new version of a WordPress plugin or theme, sometimes you need to change a part of it that might break compatibility with previous versions. Maybe you want to change the name of a function, or wrap it inside a class for better code structure. Most of these changes can be made backwards compatible by deprecating the old version and linking that to the new implementation, so it still works.

In an ideal world, you never have to break backwards compatibility. But there are cases where you simply have to break backwards compatibility in order to move forward. You can still deprecate the old version, but there is no way you can make an implementation of the old code, work with the new one.

We were facing this exact issue while developing WooCommerce 2.0. This was a big update, where we’ve basically rewritten most parts of the plugin. We couldn’t work around dropping some backwards compatibility, but paid the price in an increase of support requests after releasing that new version.

WooCommerce 2.0 broke a lot of backwards compatibility

WooCommerce 2.0 was a major update, a lot changed. We changed some vital elements in the template files, so that everybody using custom templates in their theme had to update these templates as well. While we thought to be well prepared, there were many users complaining about this. They either didn’t realise they had to update their templates, or simply didn’t know what to do. What mattered to them is that they ended up with a broken website after the update.

I posted this comment on the WooCommerce 2.0 announcement post:

I can assure you that backwards compatibility is very important to us. You simply start with the biggest changes we’ve ever done to the code since WooCommerce was first created. We decided that we had to drop some of this backwards compatibility in this 2.0 release, to remove a lot of legacy code that was holding us back for a long time.

The update strategies we’ve mentioned in this post and all previous posts always apply though. You are working with code, so it can change, yes. We do our best to keep everything working with previous versions, but sometimes it is impossible. My best practice is to use a staging environment, test everything there and clean up bugs before using it on a live website.

In the end, we’re improving WooCommerce by breaking backwards compatibility every now and then. We try to avoid it, but sometimes there is no other way.

This was an update we really needed to do, in order to move forward with the plugin. It was holding us back and we now have a better plugin foundation to continue our development on. So in retrospect it’s worth having to deal with some extra support requests. But at that time, we were all helping out in our support channels to deal with the number of tickets coming in.

How to prepare your users

We knew this update was coming and had the potential to break a lot of websites. So we started publishing blog posts detailing the changes a couple months before we released the update. We started publishing in December 2012 (WooCommerce 2.0 was eventually released on the 4th of March 2013), all the way up to a long post about preparing your website for WooCommerce 2.0. This helped a bit.

Two weeks before we released the final, we publicly announced that the 4th of March was going to be the date. I titled the post Last call for testing.

The day we released WooCommerce 2.0, shit hit the fan. Big time. All users of our plugin who read our blog posts and took the time to test the update were fine. But unfortunately, a lot of our users didn’t test before updating their live website and ended up requesting support. Our support inbox exploded and it took us a couple days, with everybody helping out, to resolve all our users issues.

What did we learn?

What surprised me the most while dealing with all these compatibility issues, was the amount of third party themes and plugins involved in this. We always try to stay in touch with these developers, who are selling their themes or plugins on websites other than The number of third party developers, who had tested their products with WooCommerce 2.0, was very low though. We clearly failed in communicating clearly that this update was going to break compatibility with their products.

Telling your users how to make sure everything still works is one thing, but convincing external parties of the same, is something completely different.

The most important lesson learned is that you should not break backwards compatibility unless you absolutely have to. Our 2.0 update was a major one, so loss of backwards compatibility can be expected. In the end, only your users (and potentially customers) will suffer from these decisions.

When you do decide to break some compatibility, make sure you clearly communicate this timely. We failed to do this properly with our large pool of third party developers, which resulted in a poor experience for our users.

Got something to say?

Drop me a line on Twitter, I'm @CoenJacobs.

About this site

Noticed how lightning fast this website is? It's powered by a Digital Ocean VPS and they are awesome. Go check it out (and get $10 in credits for free when signing up via this link)!