Does semantic versioning apply to source or binary compatibility?

Question

This question applies to any language which is written in one language ("source"), e.g. C or Java, and distributed in another ("binary"), e.g. machine code or Java byte code, using dynamic linking.

---

Suppose a user is already using version A of my library. I release a newer version B.

If he can compile his code without change against B and correctly run with B, the change from A to B is said to be source compatible.

If he can compile his code against A and correctly run with B, the change from A to B is said to be binary compatible. This situation is common when using transitive dependency graphs without isolated module loading (e.g. OSGI). X is compiled against certain versions of Y and Z, and Y was compiled against a different certain version of Z. At runtime, Y's calls into Z may not be correct and may crash.

It is possible for changes to be source compatible, but binary incompatible. It is also possible for changes to be source incompatible and binary compatible.

Which compatibility do I use for semantic versioning? Do I use source compatibility to differentiate between major and minor/patch updates, or do I use binary compatibility to differentiate between major and minor/patch updates?

---

My current motivation is a Scala library. Scala binary compatibility can be very difficult to analyze and requires an good understand of compiler details. Source compatibility and binary incompatible is very common.

This isn't some bizarre edge case; this problem can appear in most any compiled, dynamically linked language.

Answer 1

A few months later, I think I have a good conclusion.

Semantic versioning should consider both, and follow the "most changed" one.

• Breaking source compilation is an incompatible change to users of the library.
• Breaking runtime execution is an incompatible change to users of the library.

If either source compatibility or binary compatibility changes, it should -- according to semantic versioning -- be a new major version.

In my case for Scala, binary compatibility can be sometimes be rather difficult to determine. There are several JAR API diffing tools, e.g. JDiff.