jump to navigation

Deprecated Means “Don’t Touch This” October 27, 2015

Posted by PythonGuy in Uncategorized.

My favorite video game is Factorio.

The developers have been doing a great job building a remarkably stable game for something they call “experimental” or rather pre-alpha.

However, they committed a cardinal sin a few versions back, one which they did not need to do. The cardinal sin they committed was they broke backwards compatibility with mod authors.

When you’re developing software, you quickly learn that if new versions of your software doesn’t work with old version of someone else’s software, that they don’t want to use your software anymore. They call it “breaking backwards compatibility” and they call your software “broken”. After all, you had a choice and you chose to make your software fail. You broke it, and it will remain broken until everyone else updates their code or you fix the bug you introduced in your own software.

There is a way to make backwards-incompatible changes such that it isn’t backwards-incompatible. In order to explain what to do, I’m going to describe how I would replace an API that provides something called A with something that provides B. A and B are different, but they accomplish similar things. That is, you want everyone who called A to now call B.

Here’s the formula:

  1. Introduce B in parallel with A. This can be tricky, but it is necessary.
  2. Tell everyone that A is now deprecated. Do not change A anymore. If someone uses A, then somehow notify them that they should be using B.
  3. Support A until no one in the entire universe is using it anymore.
  4. Even when people stop using A, keep supporting it for as long as you can.
  5. At some point, you will want to bring in a change that will make A actually broken. Don’t do it. Instead, if they call A, return an error saying that the operation cannot work anymore.

That’s pretty much it.

Notice that A is supported for as long as possible — way beyond anything reasonable. The reason for this is simple: Old software doesn’t die. You may think you have all the old software updated, but someone somewhere does not, and if you break their software unnecessarily, then they will rightfully call your code out for being broken.

As a user of the software, I can write it so that it can talk with the new or old version, or both, if necessary. Had Factorio not been changed in such a way as to break old software, we could’ve gradually moved to the new version, kept the players happy, and been none the wiser. But instead, it’s broken for everybody, and it will be some time before we can fix it all.

As a side note, Python 3 broke backwards compatibility as well. They committed a huge sin, but one that had to be committed because there really was no way to see how to have features A and B exist together. For instance, they wanted to replace the print statement with a function, and there’s simply no way to do that. “print” either has to be a function or a statement, it can’t be both. They piled on a bunch of other backwards-incompatible changes and told people, “Python 3 is not the next version of Python 2. It is a completely different version that only bears some resemblance to each other.” See, Python 2 still works, and will work for a very long time.

And that’s what you need to do when you must break backwards compatibility: come out with something entirely new.


No comments yet — be the first.

Leave a Reply

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

WordPress.com Logo

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

Google photo

You are commenting using your Google 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: