Backwards Compatibility

This article was originally published in php|architect in April 2009 and I published it mostly as it appeared in the magazine shy of the odd formatting to fit the blog format better and updated a few year references.

Just remember, this article was written a while ago and any references to PHP 4 reflect that, take it with a pinch of salt :-)

In my last blog post, I went on a little rant about version naming standards and how that standard has helped PEAR, and other projects, to deal with their version naming and what users and developers can expect from the naming rules (e.g. seeing Foo- 0.5.0beta5 = A backwards compatibility break could happen) and so on. A version naming standard is a positive thing, but now I’m going to focus on something that is both a positive and at the same time a negative side effect of the version naming standard we keep in PEAR, something people have both praised and condemned PEAR for. Yes people, it is backwards compatibility.

The Good, the Bad, the Ugly

As I mentioned, people have praised us for our stance on backwards compatibility and people have told us that we are idiots for it. Let’s look at the “issue” from both sides, shall we.

The good thing about keeping backwards compatibility (or as it is better known, BC) religiously is that if I, as a company or a project, decide to use library X from Y repository and said library is in a stable state, then I can rest assured that my application will still run as intended even if library X gets upgraded from 1.1.0 → 1.3.0 → 1.20.0. This is very important for me as an end-user because I can sleep at night, and it makes my development efforts a lot easier.

The bad thing about backwards compatibility is that you have to, well … maintain backwards compatibility, a bit of a circle reference there, huh ? ;-) As a library / API maintainer, I feel absolutely horrified about keeping BC in my code. I need to make sure that function foo() will stay the same, return the same, and accept the same parameters, even if I refactor the internals of the code. The fact is that sometimes you release something which you believe to have awesome code as well as the most superb API design ever made, but then some new requirements, new features, or unexpected bugs happen which directly or indirectly mean you need to alter the API. Now, you need to make a decision: try to preserve backwards compatibility and thus cause more coding and headache for you or release a new major version that breaks backwards compatibility and means that you will be supporting two code bases until the majority of your users have moved over allowing you to finally put the old code base to rest (a good library maintainer would try to maintain both ;-) ).

Having heard about the good, the bad, and the ugly of backwards compatibility, how does this really affect PEAR and other big projects? Simply put, it has caused PEAR to accumulate a good amount of PHP 4 code that can not really be turned into PHP 5+ only code unless a completely new release is done under a new version number with a changed class name, 2 appended or similar. And for this reason, we have gotten some nasty stamps from people for being too conservative, holding on to PHP 4, not supporting the adoption on PHP 5, and some people have even gone so far as to say that PEAR died many years ago.

Excuses, Excuses, Excuses

To answer those “stamps”, I have to go on the defensive a bit, but for a good reason. What we did in regards to backwards compatibility has kept many companies extremely happy because we have not broken stable code out of the blue.

First off, I’d like to say this: PEAR has only accepted new packages that have PHP 5 dependency for 4 – 5 years so if anything, PEAR has been very pro PHP 5 for a long time. Plus, we have made sure all of our PHP 4 packages work just fine on PHP 5. As part of being a high quality repository of code, PEAR developers have tried to ensure that old packages do not fall into a Siberian no man’s land, so sometimes this can also be perceived as holding on to the past.

Another thing PEAR did back in the days when PHP 5 was taking its baby steps was to make sure people did not propose a package as PHP 5 only if it was just going to use sugar features like public / protected / private, or ppp if you like, because, at the time, PHP 4 was going strong. Of course we allowed PHP 5 only packages if people actually used PHP 5 specific features. Hindsight is always a great thing and we probably shouldn’t have pushed the matter so hard, oh well!

One thing to consider about promising people backwards compatibility: it will strain your development resources heavily, especially because it will mean maintaining two or more branches of similar/same code base. This resource strain is one of the reasons why PEAR developers sometimes opt for maintaining PHP 4 code that also works on PHP 5 instead of maintaining two copies of the code, PHP 4 code that works on PHP 5 and then also a PHP 5 only version. It’s open source, and you only have so much time on your hands. :-)

As you can see, these are a bunch of excuses, but to me they are fairly valid reasons because often we were putting our standards to work, enforcing them were needed, and thinking about our end users, something too few projects do, be it in PHP, C or whatever language. One excellent example is ffmpeg, a very good library to handle videos and similar formats, but they don’t believe in backwards compatibility. They, in fact, constantly break their API, don’t do any official releases to speak of, and just tell people to stuff it (just go read the Download page on their website – This has caused many people to move away from a very good library to other alternatives because they don’t want to fix their code every other day because said library maintainers are not playing ball with their end users.

Hopefully, this was useful to people who have wondered about backwards compatibility, as well as projects/companies that are either going to role out their own libraries to the public/customers or intend on picking a library or five to use in their own projects.

Think long and hard about it: do you have the resources to use a library that doesn’t have any backwards compatibility rules in place or do you have the resources to maintain a library that has backwards compatibility rules and everything that encompasses.

Put your thinking hats on ladies and gentlemen, and, until the next time, cheerio.


One Comment to “Backwards Compatibility”

  1. Amen. Maintaining BC is a *** in the ***, and costs a LOT, but it also makes the difference between a good and a bad lib. On the other hand, the option of creating completely new versions that break BC while maintaining it in an old branch, with no new features, has been used before and still sounds perfectly acceptable.

    Good article.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: