Discussion about Restangular versioning

[bostrom]

Hey @mgonto @daviesgeek @pedromarce and other interested.

What thoughts do you have any on versioning in Restangular? Looking at the project history, mainly the CHANGELOG, doesn't really reveal to me what (if any) versioning scheme has been used in the past.

I'm looking at the issues and PRs in the project and wonder how to version upcoming releases as these changes are implemented. I'd like to use semver, since it's widely used and well suited for package management dependency control (which is most important with a library like this). But semver requires the major version to be bumped whenever there's a breaking change, something that inevitably will happen sooner or later.

Now this is usually not a problem, it's just that mentally (for humans), the major version of a library is often considered the "generation" of the library, i.e. like the 2 in AngularJS 2. So also in Restangular, where there's been discussions about "Restangular 2", which has been implicated to mean version 2.x.x.

This conceptual mixup of version number for machines and "generation number" for humans is what causes me a headache now. How can we release versions introducing breaking changes without hijacking the conceptual meaning of "Restangular 2" as the "next generation" Restangular?

I'd propose to keep a strict and rolling semver of the library, bumping the major version when breaking changes occur, minor version with new backwards compatible features and patch version for backwards compatible bug fixes. This communicates to library users that when a major version is bumped, there's a greater reason to check out the CHANGELOG to see what has broken (even if it's only breaking for 1% of the users).

Meanwhile we'll have to communicate that "Restangular 2" isn't the same as Restangular v2.x.x, perhaps by calling it something else than "Restangular 2", or, since it seems to be meant as a more ore less total rewrite, one could argue that a new repository would be set up for it, like Angular 2.

To summarize, I think it's more important to keep a well known and defined versioning scheme than to reserve the major version only for huge "generation level" updates.

Please feel free to discuss!

[bostrom]

Actually Angular is also going for semver in favor for the "generation number" https://www.infoq.com/news/2016/12/angular-4