The Nodesource Blog

#shoptalk Subscribe

Node.js is SemVer

The biggest change for Converged Node.js

With v0.8, v0.10, v0.11, v0.12 (commonly casually pronounced 8, 10, 11 and 12), we have grown accustomed to Node.js's pre-1.0 versioning. So much so that they are frequently referred to dropping the "zero dot". However, the days of Node.js forever approaching version 1.0 have come to an end. Converged Node.js v4.0 is the new v1.0 and Node.js from here on out fully embraces Semantic Versioning, AKA SemVer.

When Ryan Dahl created Node, he introduced a Linux kernel style odd/even versioning scheme. Odd versions were internal for development and provided no guarantees of stability and even versions were stable releases. Version 0.12 represents the last release under that versioning scheme.

Where are 1-3?

If you have been strictly following Node.js stable releases, you may have noticed there is a gap between v0.12 and v4.0. The “missing releases” are the releases of io.js. The Node.js and io.js projects are merged under the Node.js Foundation in 2015 and are colloquially referred to as “Converged Node.js”. Converged Node.js maintains version continuity across Node.js and io.js. The io.js releases for v1.x, v2.x and v3.x are embraced as a continuum of releases. Even though long term support or maintenance are not available for io.js releases, merging the efforts of both projects allows both user communities move forward and unite with a single version history.

We are still kind of odd

Largely by chance, releases of io.js saw v2 as the stable release of that effort. io.js v1.x was quickly revved with a breaking change to v2.x, the most stable version of io.js. v3.x was largely not destined for production consumption with the entire goal of the release being the union of Node.js v0.12 with io.js v2.x. This curious trend continues out into future releases with Long Term Support (LTS) versions being cut off v4.0 first. When v4.0 graduates to LTS, v5.0 will start. v5.0 will be a stable release, but will not graduate to LTS. The subsequent LTS will come from the v6.0. The more things change, the more things stay the same.

LTS Release Schedule

SemVer Pre-release Tags

So, where do the unstable bits go? SemVer has a provision for pre-release tags and these will be released from the Master Node.js branch. The Node.js Technical Steering Committee (TSC), neé Node Core Team, has already provisioned nightlies for ongoing, more rigorous testing. Additionally, release candidate (RC) versions are cut and labeled with the rc.x flag (e.g. node4-rc.4).

SemVer Support for LTS

One of the most notable improvements to the Node.js Ecosystem with the introduction of Converged Node.js is LTS. Unfortunately, one notable area that SemVer does not define a pattern for is LTS releases. The current plan is to have versions with LTS continue the versioning of the original branch, with primarily patch versions thereafter. In the rare case that a critical fix can only be addressed with the introduction of new API, a minor bump may be necessary. This will look very much like like legacy Node.js since only the patch version will increment.

SEMVER ALL THE THINGS

From here on out all of the Node.js ecosystem fully embraces SemVer: Node.js, npm, userland modules. SemVer provides clear designations to end users about how much change has been introduced between releases. Node.js v4.0 is here and with it SemVer. Enjoy!

Further Reading

  • Semantic Versioning 2.0.0 - Given a version number MAJOR.MINOR.PATCH, increment the:
    1. MAJOR version when you make incompatible API changes,
    2. MINOR version when you add functionality in a backwards-compatible manner, and
    3. PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
* node-semver - The semver parser for node (the one npm uses)