I’m not exactly sure how you distinguish between these two things. Depending on your notion of “whole” you end up never incrementing major :–)
Also if your API has been out for long enough, you have a lot of users, and the API overhaul is such that existing code has to be rewritten to support the new one (is that your notion of whole ?). It’s often better for your users to add the version name in the library name itself (e.g. sqlite3) or rename your library.
To make my “Use your judgement” more precise, here’s a little bit more. I think semver is amenable to OCaml if we introduce the notion of systematic and non-systematic breakage. The latter being allowed for minor versions.
- Changing existing structure items in a way that systematically breaks user code if used is a major change. This includes: changing a type name or expression in an incompatible way, removing a label from a function signature, removing an argument from a function signature, adding a required argument to a function signature, adding or removing a new field to a non-abstract record etc. You get the idea.
- Changes that do not systematically break user code is a minor change. This include: adding and using type aliases, adding an optional argument to a function (though that one breaks users more often that you would like) or adding a new structure item to a module that is not explicitly designed to serve as a functor argument.
Also I often have modules (e.g. for writing backends) in which I explicitely say they can change in incompatible even between minor versions of the library. Just warn the user on the stability they should expect.
If we take the example you linked to, according to my criterions, this would have been a major version. It removes a label and renames and changes the type of a record field. Note the latter change could have been handled with a backwards compatiblily story and a minor change had the type been made abstract.
In an ideal world scattered with infinite time, users would carefully read release notes and versions numbers wouldn’t matter much. Since that world does not exist I think semver is useful to give a hint of what upgrading to a new version could entail. But it remains just that: a hint.