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.

9 replies on “How to deal with breaking backwards compatibility”

  1. Onward and upward. Out with the old, in with the new. #JFDI.

    You gave ample communication and lead time, but there will always be those who don’t listen and complain after the fact. I’m not going to say I didn’t break out in hives due to the support tsunami, but it had to be done!

  2. Thanks Coen. I think the you should not break backwards compatibility unless you absolutely have to part is key. It always amazes me how many users do not read the various update statements and simply update to new major versions.

    It would be cool if the plugin repo offered some kind of a way to work with branches, so you can continue offering bug fixes for the old branch. New users or users who are ready for making the switch get the newest branch.

    On the other hand, this might be a little complex for the majority of WP users.

  3. Unfortunately software companies (Woo included) repeatedly assume incorrectly that their customers have the ability to keep track of each and every update and change they force upon their users. Most of us own licenses to several dozen different types of applications/programs making it logistically impossible to keep up with the endless updates that rarely work as expected. Due to ignorance or arrogance software developers will almost always sacrifice compatibility to add a new feature… which is usually the reverse of what a consumer would choose.

  4. Fuck these cunts who ignore their userbase. Backward compatibility should never be broken you fucking assholes.

  5. I’m desperate! I’m just about to launch a new product catalog to 500 buyers and now find that my shopping cart is not working! My web developer took the money and ran and I haven’t a clue how to get my shopping cart to accept items. I am not a web developer and had hoped that when I updated the WooCommerce plugin it would resolve the issue.

    The message I’m receiving on the Dashboard is: Your theme has bundled outdated copies of WooCommerce template files – if you encounter functionality issues on the frontend this could the reason. Ensure you update or remove them (in general we recommend only bundling the template files you actually need to customize). See the system report for full details.

    I don’t know how to update/remove what looks to be 20+ WooCommerce Template overrides.

Comments are closed.