So since I started contributing to Three.js back in November, I’ve seen a number of breaking API changes occur such as the change of function names in the Math library (multiplyMatrix -> applyMatrix4, addVectors -> add, etc.) These are all improvements but they break code compatibility with pre-existing applications that are using Three.js.
I think that as Three.js gets more popular we need to almost promise that the existing interface of the library won’t change between minor version increments, rather only functions are added and bugs fixed. The interface only changes between major version number increments. This way if I am using say version 1.56, I can upgrade without any worries to 1.57. But if I tried upgrading to 2.57 from 1.56, I need to assume that I will have to update my code in my application.
I think that introducing this will make it easier for other people to build on top of Three.js more reliably as right now basically you can not upgrade Three.js without something probably breaking.
I would suggest adopting major version numbers to signify when interfaces have a breaking change. And minor version numbers for just adding new features and fixing bugs.
I’d suggest that we come to an agreement as to when we will introduce the first major veresion number and work to solidify the interfaces for that and then hold them fixed for as long as possible after that. Major libraries tend not to increment their major version numbers more than once a year and sometimes they can go for years without breaking compatibility.
So there is this great document that outlines the “theory” of semantic versioning, which is basically what I am advocating but in a simplified form:
It may be possible to hide a lot of Three.js’s functionality in closures and if it is in closures we can change it as needed without breaking the public API.