Increasing Three.js’s popularity via reducing API changes with semantic versioning?

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:

http://semver.org/

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.

Author: Fantashit

5 thoughts on “Increasing Three.js’s popularity via reducing API changes with semantic versioning?

  1. I can’t understand why this issue is waved off and the project won’t stick to very useful conventions. Semver is something that works really nicely and this project could easily make use of this.

    At this moment I’m helping a friend out transforming his project into something that uses both bower and grunt. It is a pain in the butt because three.js doesn’t support semver and we can not download the version we need using bower. Installing through bower should be easy, which is now clearly not. If semver is not used, this project would be better off unregistering for bower as it is not compatible with its specifications.

    Well, enough with the rant. 🙂 I would like to offer my help and make a pull request so that this project will be compatible with bower. I even would like to help setting up a nice grunt script for compilation, but also tagging on github. This makes it very easy to maintain for you. I also think bower support would be useful for many.

    But before I spend my precious time on it I would like to know if you are willing to accept such pull request.

  2. Everyone always talk about the benefits of semver but no one talks about the complications it brings. People suggesting using it tend not to be maintainers themselves.

    On paper semver is beautiful, in reality it makes the maintaining job much harder.

  3. Yeah, you’re right!! I’m unsubscribing before I get pulled back in. Use any versioning system you want. 😉

  4. I have to respectfully disagree, because I don’t see why SemVer would add more “problems” or “work”.

    SemVer is not about maintaining and fixing older/deprecated releases branch, it is JUST about giving your releases meaningful numbers.

    It also helps with registry like NPM and dependency management, especially because upgrading a dependency is not always done by a human.

    How does it cost: taking few minutes to think if the new release contains improvement and bugfix (increase patch number), contains new features but is backward-compatible (minor number), or contains backward incompatible changes (major number).

    SemVer (by itself) never forced anyone to do complex branching. You can continue using a linear workflow (e.g. tag master with the appropriate numbers once in a while).

  5. just happened across this issue. my $.02: in my experience coming from games development, with 3rd party engines generally you lock in the version you’re using on a project early on and don’t upgrade unless a release includes a feature or bug fix that specifically solves a problem you’re facing. am slowly realizing the web is a very different place in this regard, but still the current release strategy makes total sense to this user.

Comments are closed.