Versioning and breaking changes

[jnehlmeier]

I don't know how other people think about it but I am so used to semantic versioning these days that I often fall into the trap of ebean having breaking changes when upgrading only the minor version of the version number.

It just happened again when upgrading from 13.20.x to 13.25.x. Some other library was built against 13.20.x and now failed at runtime with NoSuchMethodException. The reason is/was that 13.24.0 had changed DatabaseConfig methods to allow fluid chaining which breaks binary compatibility.

I would really wish ebean incrementing the major version if binary compatibility has been broken so everyone knows to check release notes and not simply/blindly upgrade library.

[rob-bygrave]

Well yeah, my mistake really. I'm correct in thinking there was a library compiled against 13.20.x and it wasn't recompiled against 13.25.x and so yeah we see the NoSuchMethodException due to the change to fluid style setters [and the fix requires that library to be recompiled against 13.25.x].

Yes, a change to fluid style setters is binary breaking change - my mistake really.

[jnehlmeier]

Ok, this can happen. Changing a method return type is little bit more hidden. In the past deprecated methods had been removed without increasing the major version. That is the other situation I can remember I stumbled upon.

For some time now conventional commits are being adopted by various projects. Based on that convention commits can be parsed and a semantic version can be computed automatically (in addition a changelog could be generated as well).

So for example a commit like refactor(api)!: Change DatabaseConfig to fluid methods or cleanup!: remove deprecated methods would tell the system a breaking change (the exclamation mark) causing the major version to be incremented (based on the previous tag) and that breaking change could appear in an api section of a generated changelog.

It takes a bit of work to setup but once it works it is pretty nice.