Babylon package versioning
I am not sure if you noticed, but Babylon.js 5 was (quietly!) released. I’m also not sure if you noticed that we are already in version 5.4.0! Let’s talk about why :-)
For those who knows Babylon for a long time it might be a little strange to see a minor release so quick after a major release was published. Ever since the version is available on npm we have used a different versioning schema to publish our releases. Once a stable version was released, we have published it to our CDN, published it to npm, and then just started working on the next one. Bug fixes and new features would go to this next version’s prerelease versions and eventually released when the time came to release a new stable version.
I am saying stable, but we actually always considered all of our versions stable. and we recommended people using our preview version (that’s the name (and npm tag) we gave to our pre-release versions) in production. This is why you might see production websites using babylon 5.0.0-alpha.24 or 4.2.0-beta.5. Those were fully tested by us and contained bug fixes that were not available in the “latest stable”.
This schema was sometimes hard to explain. And hard to defend! We call it alpha, beta, rc, but we state — this is stable, use it! And we only rarely released a patch to a stable version. The latest example is the patch release 4.2.1 that was released because of a major change in the browsers which prevented our shaders from working correctly. We did recommend everyone to use the preview version (which was patched as well), but people using npm and not part of our forum or following our github repository would have been stuck with a stable version that simply doesn’t work.
The reasoning behind this kind of behavior was that at its core, Babylon.js versions are backwards compatible. Meaning — we actually never need a major version! And since we are backwards compatible, upgrading to a new version is easy. Just install the next one, we guaranty we will do whatever we can to make everything work the same way you did it before. This is good in theory, but in reality, there are things that are out of our control. I gave the browser’s change as an example before, but there are many others. Web standards change, and if we didn’t abstract them well enough, we will have to introduce breaking changes.
Having one major release every year or so also allowed us as a team to prepare for this release. Make a nice trailer, make an awesome demo, have a nice party. On the downside it also meant that we had no “stable” activity for a year and more. If you looked at our stable release before 5.0.0 was released, it would look like the package is stale. Last published — over a year ago. But we did constantly release preview versions! Don’t they count?… Not according to npm they don’t.
But having a “stable” preview version also frowned upon by many production websites that refused to use our preview version. It is actually quite understandable. You wouldn’t want to see “alpha” in your production website. Even if the devs guarantee that it’s stable, and working, and bug free. It can look very bad in your logs, in your package.json, in your build system, and when presenting it to your CTO :-)
We have listened and have thought — if we already take out versions as stable, why don’t we release them under one major version and provide everyone with a stable version — fully tested, ready for production? Why do we need to release alpha and beta versions, if we are already patching bugs and making our framework stable constantly? Especially if we are backwards compatible? We eventually came up with a new schema we were all happy with and we do hope our users will be happy with it as well.
The general gist is — we release a major version approximately once a year. In the time between major releases, we will release a minor version once a week (only if changes were made to the framework), and patches to those minor versions if needed during this week. This will all be controlled by an automated publish system and will be accommodated by a detailed changelog that would be generated automatically.
We still have a prerelease of the next major version. We will only publish this if (and only if) there are major breaking changes that we don’t want to have in our master branch yet, or if there are features that are totally not ready for production. So far, we didn’t have any of those, so we never released 6.0.0-alpha.0. But we will do this for sure when needed. Until then, the preview version would match the stable version.
NPM will always have out latest stable version. Those will not be tagged (and thus receive the “latest” tag. Prereleases, if released, will be tagged as “preview”. So you can use "babylonjs": "^5.0.0" in your package.json and always get the latest stable version. No breaking changes — guaranteed.
Our CDN will behave the same — https://cdn.babylonjs.com/babylon.js will host the latest stable version. http://preview.babylonjs.com/babylon.js will host the latest preview version. If you checked those two files now, you would find out they are the same! The reason was already explained above. You didn’t read it, did you?…
This system was put to test when we released 5.0.0 and made a few patches till we released 5.1.0 a week after. Everything worked as expected and things seem to be stable now. We also have a detailed changelog, based on PRs and changes made to every package in our repository. You can find the changelog here — https://github.com/BabylonJS/Babylon.js/blob/master/CHANGELOG.md
The changelog is updated on every new version released and is branch-dependent. Once we have our preview branch it will have its own changelog, taking the different prerelease versions into account.
A simpler version of this blog post can be found here — https://doc.babylonjs.com/divingDeeper/developWithBjs/frameworkVers. This page also describes which files we host on our CDN, how we deal with nightlies and so on.
And of course, if you have any questions feel free to contact us at our forum (https://forum.babylonjs.com).
Stay awesome!!
