So, now that I have promised SemVer conformance, almost immediately, I run up against an ambiguity: API (application programming interface) vs. ABI (application binary interface) compatibility.
The difference is between compatibility of source code (API) and compatibility of compiled shared libraries (ABI). Clearly, any incompatible API change necessitates an incompatible ABI change. However, it is possible to make an incompatible ABI change that corresponds to a COMPATIBLE API change.
SemVer does not say anything about ABI. It only mentions API. Thus, one can apply SemVer to the API or the ABI for deciding when to increment the MAJOR version number.
* Option 1: increment the MAJOR version number upon incompatible ABI changes.
* Option 2: increment the MAJOR version number upon incompatible API changes.
Option 1 ensures that a user can compile and install Minor and Patch releases of the same Major version and simply expect their preexisting compiled KIM Models and Simulators to "just work"
Option 2 only ensures that if the user compiles and installs the new KIM API version and then recompiles their existing KIM Models and Simulators, that everything will "just work" (without changing any source code).
Option 1 would be most convenient, but would lead to more rapid increments of the MAJOR version number. Also, it can be quite difficult to correctly identify when the ABI changes incompatibly, and thus the chance of releasing versions of the KIM API with "incorrect" SemVer versions increases.
Option 2 is easier to correctly assign SemVer versions for and will result in fewer MAJOR version increments. However, it may require users to recompile their Models and Simulators more often.
Based on the above, I suggest that the KIM API package follow "Option 2". That is, the versioning will strictly follow the SemVer Specification as applied to the API. ABI incompatibilities will not be strictly accounted for by the versioning scheme.
I would be very interested in the KIM communities thoughts on this issue. I'm willing to go with "Option 1" if there are enough people with good arguments who want it.
So, please reply with your comments, thoughts, and suggestions.