Clearly document our versioning policy

[mglukhovsky]

I wrote this comment on HN:

We have a stable release (v2.0) for those who cannot tolerate breaking changes.

Feature releases (e.g. 2.1, 2.2) include new features and do break compatibility on occasion (so we can quickly introduce new behavior). Any breaking changes are well-documented in the release notes[1], so you can have a smooth upgrade path.

Minor releases (e.g. 2.1.1, 2.1.2) do not have breaking changes, only bugfixes and minor improvements.

We documented some of this in our migration docs (if I remember), but we should add a basic article describing our versioning policy clearly.

[bryanlarsen]

Cool, just as long as that's up front and clear. Strictly following semver implies quickly increasing major version numbers, so there are very good reasons not to follow semver. But semver is quickly becoming an accepted practice, so if you don't follow it, stating that clearly and up front is probably a good idea.

[danielmewes]

A small correction: We don't actually have a release with "longterm support" yet.

If breaking changes are not an option at all, the best bet is usually to stay on the latest point release of whatever version your app uses, e.g. 2.0.5 would be the latest release we've made for the 2.0.x series. However those releases usually don't receive bug fixes anymore once the next

For users who absolutely rely on a specific feature release (e.g. 2.0.x or 2.1.x), we can offer to manually backport critical fixes that affect them as part of a commercial support contract.

[stuartpb]

If not long-term support, it'd be nice to explain what major versions are supposed to denote in this system.

[chipotle]

This seems like it's a bit too short for a standalone article just about version numbers, but our only FAQ at this point is about RethinkDB architectural details. Maybe it does need to have an article in "Getting Started" after all?

And, yes, I agree with @stuartpb -- the way we use version numbers really does come across as non-standard. If 2.1 → 2.2 can introduce a backwards-incompatible change, what would a jump from, say, 2.4 → 3.0 imply?

[danielmewes]

Maybe the explanation of our versioning scheme should be a paragraph on http://rethinkdb.com/docs/install/ ?
It would also fit well into http://rethinkdb.com/docs/migration/ , though that article would need to be restructured a bit (that might be a good idea in general). Most of it is about migrating from RethinkDB versions older than 1.13, which few users will run into at this point.

If 2.1 → 2.2 can introduce a backwards-incompatible change, what would a jump from, say, 2.4 → 3.0 imply?

That's a great question, and I think it's not actually well defined so far. We've done this only once from 1.16 to 2.0, and then it simply denoted production readyness. It's unclear what the next jump from 2.x to 3.0.0 could indicate.