RFC: Follow SemVer

[erhathaway]

I think Knex is great! But the fact that it doesn't follow SemVer has caused problems for me multiple times - especially when maintaining packages and microservice architectures.

The issue:

Breaking changes occur and that aren't reflected by a major version increment.

There are lots of examples of breaking changes occurring in this library. I would argue that each one should have been a major version bump.

Examples:

• Add client property to QueryBuilder type #3541 - An interface was extended to include a new attribute
• 0.20.11 no longer exposes Bluebird interfaces #3704 - An exposed type accessed through the public API changed.

Obviously, you could argue that neither was a breaking change. However, I believe most packages would consider them breaking changes.

A proposed solution:

Use SemVer for all breaking changes.

https://semver.org/

SemVer is good because it lets consumers know about compatible changes and gives better trust in quickly bumping security patches.

In this library there seems to be somewhat of a community resistance of sorts to major version bumps. I feel like these things can happen subconsciously, but maybe we should have a discussion on reevaluating this position? It's my opinion, that major version bumps don't always need to reflect milestones 😄

TL;DR

I'd like to start a discussion around the possibility of Knex following a strict version of SemVer to avoid issues with breaking changes.

[erhathaway]

I just found #912. So this ticket would be to reopen discussion on it.

[briandamaged]

Howdy! We're actually actively working towards the official 1.0.0 release. At that point, we hope to be able to maintain SemVer going forward.

However, there's currently a bit of tech debt we're trying to pay down that will result in a few more breaking changes. So, we're trying to wrap up some loose ends on that before we make the jump. (Otherwise, knex might jump to version 2.0.0 or 3.0.0 shortly after the 1.0.0 release)

[briandamaged]

Actually, let me rephrase that: we're paying down tech debt, and we suspect that this might result in a few more breaking changes. However, we're doing what we can to avoid this. (Ex: I'm currently on my 3rd of 4th draft of redesigning some of the Transaction details. The first few drafts would have interfered with some work-arounds that various users had implemented for seemingly-unrelated issues)

[erhathaway]

@briandamaged thanks for the quick response!

This is only my opinion, so definitely take it with a grain of salt, but maybe the 1.0.0 release is being put on a pedestal? I've seen comments about it dating back to at least 2016. Maybe milestones could be separated out from major version numbers? Given that Knex is so awesome and widely popular, It would be very valuable to have real SemVer asap. I feel like this is especially true given that I bet a lot of people don't know Knex isn't following semver - since its almost an implicit understanding now in the node ecosystem that packages do it.

[elhigu]

Nothing to do here... knex already follows semver (semver doesn't enforce anything for ver < 1.0). Closing as this has been already discussed through in other issues.

[elhigu]

Though after 1.0 especially with typing changes people needs to be careful, since those are really often breaking changes.

[erhathaway]

semver doesn't enforce anything for ver < 1.0

I would argue that this is part that is causing problems. Plenty of folks do semver pre 1.0 b/c of the benefits it has. I'm asking for a discussion about possibly enforcing it pre '1.0' b/c:

• '1.0' hasn't happened yet
• its been years of talking about a '1.0' release
• breaking changes are causing a lot of problems for consumers of this widely used library (especially with the types)
• I would argue that the majority of consumers of this library implicitly think that semver is currently being followed especially given its been around so long, so many people use it, and other libraries build upon it - like Bookshelf

[elhigu]

@erhathaway all true except for semantics about what following semver means (*). Those reasons were pretty much the same why I started the discussions about releasing 1.0 #1331 I'm glad that it is finally happening and nobody is denying nor downplaying importance of that.

The issue was closed because there is no specific action needed to get this done. Semver is already followed and as a separate issue the stable release is also on its way.

*) Semantics nitpicking part...

Plenty of folks do semver pre 1.0 b/c of the benefits it has. I'm asking for a discussion about possibly enforcing it pre '1.0' b/c:

As I mentioned earlier knex has been following and enforcing semver already years https://semver.org/#spec-item-4 .

I suppose you wanted to request for enforcing some scheme of notifying about breaking changes below 1.0 release. Like for example doing always minor version update on breaking change and patch version when there is no breaking changes, but only bug fixes / new features.

Knex has been trying to follow that guideline as well and in addition to that document all the breaking changes (lately those hasn't seem to be listed in the changelog, but in a separate upgrading document).