Follow SemVer

[keithamus]

Backbone.JS is a project with a large following, but regular "minor versions" (e.g 1.1.0) break compatibility with existing Backbone codebases.

To make it easier for developers to determine if a new version of Backbone includes backwards-compatible features vs backwards-incompatible api changes, Backbone's versioning scheme should follow semantic versioning (SemVer)

The gist of semver is as follows:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
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.

This would make the existing version (1.1.0) a 2.0.0 version (as most of the changes broke existing API) which would clearly indicate to developers that the API is different, and allow developers to utilise npm's wildcard versions (e.g "1.x", "~1")

[jashkenas]

Thanks, but strictly following "semantic" versioning wouldn't work out very well for Backbone. Given that the project is almost all surface area, and very little internals, almost any given change (patch, pull request) to Backbone breaks backwards-compatibility in some small way ... even if only for the folks relying on previously undefined behavior.

If we strictly followed "semantic" versioning, it would probably be Backbone.js 43.0.0 by now — which doesn't help anyone evaluate the actual progress of the project.

So, as I like to joke — not "semantic" versioning, romantic versioning.

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make a major new release, or significantly update and/or stabilize the API.
MINOR version when you add minor new features.
PATCH version when you make tiny changes, likely to go unnoticed by most.

This allows folks, immediately upon hearing about a new release, to get a rough sense of its scope. As to backwards compatibility — ideally every release, even major ones, are backwards-compatible. And when they can't be, because an API is changing, it should be done in a way that isn't too difficult to upgrade.

But avoiding any change to the API, and waiting for a "MAJOR" release to be ready would be a terrific impediment to progress. And the alternative of frequently incrementing the MAJOR version number is incredibly unhelpful.

Honestly, I'd prefer a simpler scheme that just used BIG.SMALL version numbers — like most desktop applications do ... but I'd worry about it breaking package managers and other tooling.

[spadgos]

What's the problem with being at Backbone 43.0.0?

• Sent from Chrome 32.0.1700

[leadVisionary]

+1 for spadgos@ question. Version numbers are arbitrary. For some reason, we have agile web apps trying to keep within the same ranges as OSes. Many apps freak out about going past 10...but most of the projects you're modeling off of (Windows, Linux, etc) have 1 year/multi-year dev cycles before release, so 1.x -> 2.x is a big deal. An agile project moves very quickly, incrementing quickly makes sense too.

[mxriverlynn]

I also disagree with the reasoning behind this.

Marionette is on v1.2.3 right now, and is doing it's best to follow strict semantic versioning. So far, we haven't had any issues even though we are "all surface area" as well. We've added new features. We've fixed bugs. But v1.0 is still compatible with v1.2.3. We've deferred tickets for a v2 release when they are API or expected behavior breaking changes.

Major releases with breaking changes don't have to happen every week when a pull request is accepted. These can (and should) be pooled in to major release that encompass enough value for a large release with a major version bump.

As it stands, breaking compatibility in a v1.1 release causes a lot of pain for plugin and add-on developers, like the MarionetteJS team. We had to back-fill behaviors with patches in our code, so that we can remain viable for both v1.0 and v1.1... it's not a fun situation. The ripple effects of a core library like Backbone having breaking changes, are enormous... it's not just Backbone that is affected.

[bobholt]

I agree this seems more like a case of "don't want to" rather than "can't." Breaking changes such as #2461 have no real sense of urgency, and could have waited for a major version update if you don't want the 43.0.1 problem.

For me, the biggest problem with Backbone not respecting semver (among other things) is in teaching and evangelizing Backbone. It's not great to tell a group of students or potential customers that everything in your stack is going to work in a certain way... except for Backbone.

There have always been two huge caveats when "evangelizing" Backbone: it's not AMD out of the box, and it doesn't respect SemVer, so don't take the version numbers seriously. One of those is fixed. Let's fix the other.

[knowtheory]

Honestly, I'd prefer a simpler scheme that just used BIG.SMALL version numbers — like most desktop applications do ... but I'd worry about it breaking package managers and other tooling.

@jashkenas we could just always leave the 3rd digit at .0 :)

That'd probably map semantically to SemVer a little closer than what we're doing right now. Maybe that'd tamp down on some of the passive-aggressive crypto-political sniping about how it's somehow technically wrong not to follow SemVer.

I think Bob's point is right in that it's more important to clearly articulate what system we follow, irrespective of what system we follow.

p.s. I did not mean to imply that @keithamus's issue is passive aggressive and I'm sorry if it came off that way. Definitely legit to discuss how Backbone communicates changes to users.

[lukeasrodgers]

👍 for semver. I am primarily interested the version of a given piece of software not as an index of its progress but of its compatibility.

Generally, after 1.0 (when I'd expect things to be mostly stable and working), version numbers are largely meaningless as indicators of progress. Software X at version 10 may be much less mature, have fewer features than Software Y at version 2. If you want to know about the progress of a piece of software, you have to look at its changelog or roadmap.

Knowing that Backbone (or whatever) is at 2.4.3 means nothing in terms of its features. It should, however, mean that I can upgrade from my 2.0.4 without anything breaking.

[jamesplease]

If we strictly followed "semantic" versioning, it would probably be Backbone.js 43.0.0 by now — which doesn't help anyone evaluate the actual progress of the project.

A very minor / maybe nonexistent problem. Not following semver? Big problem.

[Anachron]

👍, semver is a must-have for such a big project.

[braddunbar]

I'm with @knowtheory. 43.0.0 looks a bit odd but I think 1.43.0 would be fine and no one would get surprise breakage after npm install.

[Anachron]

Who cares about version numbers being high?
It's a standard, if you can use it, you should use it.
I don't even understand why this discussion is going for so long.

[jdalton]

👍 It would have prevented some of the issues in #2996 and #2997, and problems others have had w/ several other Backbone releases.