[GH-ISSUE #162] Optional addition of a binary version #1838

New Issue

GiteaMirror · 2026-04-20T09:29:50-05:00

GiteaMirror commented

2026-04-20 09:29:50 -05:00

Originally created by @LasseBlaauwbroek on GitHub (Sep 10, 2013).
Original GitHub issue: https://github.com/semver/semver/issues/162

The current spec only seems to cover the static/source version of software. There is, however, also the binary version of the software.

I see two use-cases:

A developer is developing an application, and has some dependency on a library. This library is distributed together with the application. If a new version of the library is released, it can only be included in the next version of the application itself. The application is then recompiled.
A developer is developing an application, is also has a dependency on the library, but the library is not distributed together with the application. Some package manager on the computer of the end user has to dynamically link the correct package with the application when it is executed. The package of the application is not recompiled in this case.

For the first use-case, only static/source level compatibility is relevant, because the application is recompiled when it is redistributed.

For the second use-case only binary level compatibility is relevant. An application may only be linked to a library if that version is completely compatible with the version it was intended for. Now, one might say the binary version indicator of a library is equivalent to the major indicator of the source level, because that is the only time there are breaking changes. However, this is not always the case. For an example and more information on binary vs source compatibility see:
http://blogs.msdn.com/b/jmstall/archive/2008/03/10/binary-vs-source-compatibility.aspx

I propose a separate indicator for binary compatibility, which consists of only one number. Three numbers are not necessary because a library is either binary compatible or it is not. A versioning might then look something like x.y.z|b where b is the binary level indicator. Other formats are, of course, also possible.

A binary level indicator is not always relevant (for example in a web-service) so it should be optional. EDIT: In case the binary level indicator is not present, but a package manager must make a decision about using a version based on binary compatibility, the major version indicator may be used instead of the binary version indicator.

Originally created by @LasseBlaauwbroek on GitHub (Sep 10, 2013). Original GitHub issue: https://github.com/semver/semver/issues/162 The current spec only seems to cover the static/source version of software. There is, however, also the binary version of the software. I see two use-cases: - A developer is developing an application, and has some dependency on a library. This library is distributed together with the application. If a new version of the library is released, it can only be included in the next version of the application itself. The application is then recompiled. - A developer is developing an application, is also has a dependency on the library, but the library is not distributed together with the application. Some package manager on the computer of the end user has to dynamically link the correct package with the application when it is executed. The package of the application is not recompiled in this case. For the first use-case, only static/source level compatibility is relevant, because the application is recompiled when it is redistributed. For the second use-case only binary level compatibility is relevant. An application may only be linked to a library if that version is completely compatible with the version it was intended for. Now, one might say the binary version indicator of a library is equivalent to the major indicator of the source level, because that is the only time there are breaking changes. However, this is not always the case. For an example and more information on binary vs source compatibility see: http://blogs.msdn.com/b/jmstall/archive/2008/03/10/binary-vs-source-compatibility.aspx I propose a separate indicator for binary compatibility, which consists of only one number. Three numbers are not necessary because a library is either binary compatible or it is not. A versioning might then look something like `x.y.z|b` where `b` is the binary level indicator. Other formats are, of course, also possible. A binary level indicator is not always relevant (for example in a web-service) so it should be optional. EDIT: In case the binary level indicator is not present, but a package manager must make a decision about using a version based on binary compatibility, the major version indicator may be used instead of the binary version indicator.

GiteaMirror added the question label 2026-04-20 09:29:50 -05:00

GiteaMirror closed this issue

2026-04-20 09:29:51 -05:00

GiteaMirror commented

2026-04-20 09:29:52 -05:00

@LasseBlaauwbroek commented on GitHub (Sep 17, 2013):

Edited issue with some more information.

@LasseBlaauwbroek commented on GitHub (Sep 17, 2013): Edited issue with some more information.

GiteaMirror commented

2026-04-20 09:29:53 -05:00

@huntc commented on GitHub (Nov 18, 2014):

Thanks for the great initiative @LasseBlaauwbroek.

Just so I'm clear... the b would indicate binary compatibility with the previous minor/patch release right? For example, the following:

2.4.0  binary incompatible with anything before it
2.4.1b binary compatible with 2.4.0
2.4.2  binary incompatible with anything before it including 2.4.1b
2.4.3b binary compatible with 2.4.2

@huntc commented on GitHub (Nov 18, 2014): Thanks for the great initiative @LasseBlaauwbroek. Just so I'm clear... the `b` would indicate binary compatibility with the previous minor/patch release right? For example, the following: ``` 2.4.0 binary incompatible with anything before it 2.4.1b binary compatible with 2.4.0 2.4.2 binary incompatible with anything before it including 2.4.1b 2.4.3b binary compatible with 2.4.2 ```

GiteaMirror commented

2026-04-20 09:29:55 -05:00

@bhetland commented on GitHub (Nov 19, 2014):

This 'b' indicator would only refer to the immediate preceding version, right? How would the "user" --who decides whether to use the new version, or stay with the old one due to compatibility concerns-- then know which exact version was the preceding one? For example, they might have version 2.4.2, but now they notice there's a new 2.4.4b. Is it compatible with their 2.4.2? Maybe... for example if the developer/marketing decided to skip the 2.4.3. Or I would believe if there actually was a 2.4.3b.

I guess my point is that the 'b' indicator doesn't actually provide the complete information, as some judgements would rely on being able to find information elsewhere (such as which versions did actually exist in the past).

If the user sees a new version 2.5.0b, would it be easy to determine if it is compatible with his/her 2.4.6? (This one could perhaps be "prohibited" by never allowing the combination x.y.0b, but the bump of the minor version may not imply binary incompatibility.)

Something that also happens in real life: Suppose the developer had a version 2.4.0, then did a bugfix so they got a 2.4.1. Or it could be intended as binary compatible, but their fix broke the compatibility without them discovering it, so they marked it 2.4.1b (incorrectly, but it just reflects a promise really.) Oops, so they discover this and again "fix" the binary incompatibility. Now, the fixed 2.4.2 is again binary compatible with 2.4.0, but should they call it 2.4.2b?

@bhetland commented on GitHub (Nov 19, 2014): This 'b' indicator would only refer to the immediate preceding version, right? How would the "user" --who decides whether to use the new version, or stay with the old one due to compatibility concerns-- then know which exact version was the preceding one? For example, they might have version 2.4.2, but now they notice there's a new 2.4.4b. Is it compatible with their 2.4.2? Maybe... for example if the developer/marketing decided to skip the 2.4.3. Or I would believe if there actually was a 2.4.3b. I guess my point is that the 'b' indicator doesn't actually provide the complete information, as some judgements would rely on being able to find information elsewhere (such as which versions did actually exist in the past). If the user sees a new version 2.5.0b, would it be easy to determine if it is compatible with his/her 2.4.6? (This one could perhaps be "prohibited" by never allowing the combination x.y.0b, but the bump of the minor version may not imply binary incompatibility.) Something that also happens in real life: Suppose the developer had a version 2.4.0, then did a bugfix so they got a 2.4.1. Or it could be _intended_ as binary compatible, but their fix broke the compatibility without them discovering it, so they marked it 2.4.1b (incorrectly, but it just reflects a promise really.) Oops, so they discover this and again "fix" the binary incompatibility. Now, the fixed 2.4.2 is again binary compatible with 2.4.0, but should they call it 2.4.2b?

GiteaMirror commented

2026-04-20 09:29:55 -05:00

@huntc commented on GitHub (Nov 19, 2014):

Good points @bhetland - in summary a means of expressing what the version is binary compatible with could be useful. Right?

@huntc commented on GitHub (Nov 19, 2014): Good points @bhetland - in summary a means of expressing _what_ the version is binary compatible with could be useful. Right?

GiteaMirror commented

2026-04-20 09:29:56 -05:00

@huntc commented on GitHub (Nov 19, 2014):

An idea then, is to qualify the b. Here's an idea:

2.4.0     binary incompatible with anything before it
2.4.1b4.0 binary compatible with 2.4.0
2.4.2b4.0 binary compatible with 2.4.0 and 2.4.1
2.4.3     binary incompatible with anything before it including 2.4.1 and 2.4.2
2.4.3b4.3 binary compatible with 2.4.3

The promise on binary compatibility is now made explicit.

@huntc commented on GitHub (Nov 19, 2014): An idea then, is to qualify the `b`. Here's an idea: ``` 2.4.0 binary incompatible with anything before it 2.4.1b4.0 binary compatible with 2.4.0 2.4.2b4.0 binary compatible with 2.4.0 and 2.4.1 2.4.3 binary incompatible with anything before it including 2.4.1 and 2.4.2 2.4.3b4.3 binary compatible with 2.4.3 ``` The promise on binary compatibility is now made explicit.

GiteaMirror commented

2026-04-20 09:29:56 -05:00

@LasseBlaauwbroek commented on GitHub (Nov 19, 2014):

My orininal idea was not to let 'b' be a modifier, but a variable, just like x, y and z. The idea is that binary compatibility is often completely separate from source compatibility. Sometimes you release many versions of your library, but they are all binary compatible because you only added API's. If you, however, just want to clean up your code and remove some overloaded function, the source API may stay completely the same, while you are no longer binary compatible (see link in original post).

A version progression may then look like this:

1.0.0|1 <-- Initial release
1.0.1|1 <-- Bug fix, the same binary version
1.1.0|1 <-- Added new API, but all old API's are still compatible.
1.1.0|2 <-- A binary incompatible change to the new API, but the lib is still source compatible with 1.1.0
1.2.0|2 <-- Another new API added, rest is fully compatible with the previous version
2.0.0|3 <-- Complete overhaul of lib

This means, for example, that if an application specifies a dependency on 1.1.0|2, a package manager can safely upgrade to 1.2.0|2. A dependency on 1.1.0|1 however means no upgrade can be done.

However, if we recompile the program depending on 1.1.0|1, we can safely go to 1.1.0|2 and even to 1.2.0|2.

Note that it will not be possible to use 1.0.1|1 when there is a dependency on 1.1.0|1, because having the same compatibility number means the newer version can be used in place of the older version, and not vice-versa. This is because there can be new API's introduced in the new version.

@LasseBlaauwbroek commented on GitHub (Nov 19, 2014): My orininal idea was not to let 'b' be a modifier, but a variable, just like x, y and z. The idea is that binary compatibility is often completely separate from source compatibility. Sometimes you release many versions of your library, but they are all binary compatible because you only added API's. If you, however, just want to clean up your code and remove some overloaded function, the source API may stay completely the same, while you are no longer binary compatible (see link in original post). A version progression may then look like this: ``` 1.0.0|1 <-- Initial release 1.0.1|1 <-- Bug fix, the same binary version 1.1.0|1 <-- Added new API, but all old API's are still compatible. 1.1.0|2 <-- A binary incompatible change to the new API, but the lib is still source compatible with 1.1.0 1.2.0|2 <-- Another new API added, rest is fully compatible with the previous version 2.0.0|3 <-- Complete overhaul of lib ``` This means, for example, that if an application specifies a dependency on `1.1.0|2`, a package manager can safely upgrade to `1.2.0|2`. A dependency on `1.1.0|1` however means no upgrade can be done. However, if we recompile the program depending on `1.1.0|1`, we can safely go to `1.1.0|2` and even to `1.2.0|2`. Note that it will not be possible to use `1.0.1|1` when there is a dependency on `1.1.0|1`, because having the same compatibility number means the newer version can be used in place of the older version, and not vice-versa. This is because there can be new API's introduced in the new version.

GiteaMirror commented

2026-04-20 09:29:57 -05:00

@gaborcsardi commented on GitHub (Nov 19, 2014):

I don't think it is a good idea to mix binary compatibility with version numbers. The reason is simply that binary compatibility depends on additional factors, like compilers, compiler versions, OS versions, etc. The version number should refer to the source code, imho.

@gaborcsardi commented on GitHub (Nov 19, 2014): I don't think it is a good idea to mix binary compatibility with version numbers. The reason is simply that binary compatibility depends on additional factors, like compilers, compiler versions, OS versions, etc. The version number should refer to the source code, imho.

GiteaMirror commented

2026-04-20 09:29:57 -05:00

@LasseBlaauwbroek commented on GitHub (Nov 19, 2014):

Yes, because of that, I propose to add a new independent indicator separated by '|', for binary compatibility.

@LasseBlaauwbroek commented on GitHub (Nov 19, 2014): Yes, because of that, I propose to add a new independent indicator separated by '|', for binary compatibility.

GiteaMirror commented

2026-04-20 09:29:58 -05:00

@gaborcsardi commented on GitHub (Nov 19, 2014):

My point is, you cannot express binary compatibility with a version number, unless you include os versions, compiler versions, as needed. Having a version number like 1.0.0|1 is often meaningless in itself. E.g. if a C library binary was built on OSX Snow Leopard, then a binary 1.0.1|1 built on OSX Mavericks is not binary compatible with it, because the two systems are not binary compatible. Just to give a concrete example.

Binary compatibility very much depends on the language, platform, etc. so I think it is better to leave its "versioning" to people creating the binaries. E.g. in the case above they would create a binary called 1.0.0+snow and another one called 1.0.0+mavericks.

@gaborcsardi commented on GitHub (Nov 19, 2014): My point is, you cannot express binary compatibility with a version number, unless you include os versions, compiler versions, as needed. Having a version number like `1.0.0|1` is often meaningless in itself. E.g. if a C library binary was built on OSX Snow Leopard, then a binary `1.0.1|1` built on OSX Mavericks is not binary compatible with it, because the two systems are not binary compatible. Just to give a concrete example. Binary compatibility very much depends on the language, platform, etc. so I think it is better to leave its "versioning" to people creating the binaries. E.g. in the case above they would create a binary called `1.0.0+snow` and another one called `1.0.0+mavericks`.

GiteaMirror commented

2026-04-20 09:29:59 -05:00

@LasseBlaauwbroek commented on GitHub (Nov 19, 2014):

Well, I assume we are making use of some sort of package repository. And it is the respoinsibility of the package maintainers to make sure all packages are compiled in a consistent way and for the same type of systems (OS, etc). For example, you have different package repositories for Snow and Mavericks. The only thing the binary compatibility indicator means is that if you use a consistent toolchain and system, two versions with the same compatibility indicator can be interchanged.

@LasseBlaauwbroek commented on GitHub (Nov 19, 2014): Well, I assume we are making use of some sort of package repository. And it is the respoinsibility of the package maintainers to make sure all packages are compiled in a consistent way and for the same type of systems (OS, etc). For example, you have different package repositories for Snow and Mavericks. The only thing the binary compatibility indicator means is that if you use a consistent toolchain and system, two versions with the same compatibility indicator can be interchanged.

GiteaMirror commented

2026-04-20 09:29:59 -05:00

@gaborcsardi commented on GitHub (Nov 19, 2014):

Are you suggesting to store binary incompatible package in different repositories? So how are then two packages in the same repository binary incompatible? It is exactly the toolchain that makes packages binary incompatible, no?

@gaborcsardi commented on GitHub (Nov 19, 2014): Are you suggesting to store binary incompatible package in different repositories? So how are then two packages in the same repository binary incompatible? It is exactly the toolchain that makes packages binary incompatible, no?

GiteaMirror commented

2026-04-20 09:30:00 -05:00

@LasseBlaauwbroek commented on GitHub (Nov 19, 2014):

As I see it, there are two kinds of binary (in)compatibilities. One is caused by using different toolchains and platforms (although I would say this last one is debatable), and can be solved by using the same toolchain and platform per repository.

The other one is caused by API progression. Sometimes a new version of a library is introduced that is fully binary compatible, and sometimes a new version is not binary compatible, and requires that the depending application is recompiled. This problem could be solved by using the binary compatibility indicators.

@LasseBlaauwbroek commented on GitHub (Nov 19, 2014): As I see it, there are two kinds of binary (in)compatibilities. One is caused by using different toolchains and platforms (although I would say this last one is debatable), and can be solved by using the same toolchain and platform per repository. The other one is caused by API progression. Sometimes a new version of a library is introduced that is fully binary compatible, and sometimes a new version is not binary compatible, and requires that the depending application is recompiled. This problem could be solved by using the binary compatibility indicators.

GiteaMirror commented

2026-04-20 09:30:00 -05:00

@FichteFoll commented on GitHub (Nov 19, 2014):

I don't really understand the problem here, but to me this sounds like a 100% toolchain issue. If a new version requires a new build from the dependency, the toolchain should handle that. If it doesn't, the toolchain should handle that as well. In the end that would mean you as a developer would have to specify the "binary compatible versions" of a version (so, a list of versions that are effectively using the same binary) and the toolchain should check if the previous version was in that list, somehow.

If you wanted to get fancy with semver, you could do stuff like 1.2.2+bin.compat.1.2.0 (meaning the binary(ies) used with a version of or higher than 1.2.0 are compatible) without violating the spec.

@FichteFoll commented on GitHub (Nov 19, 2014): I don't really understand the problem here, but to me this sounds like a 100% toolchain issue. If a new version requires a new build from the dependency, the toolchain should handle that. If it doesn't, the toolchain should handle that as well. In the end that would mean you as a developer would have to specify the "binary compatible versions" of a version (so, a list of versions that are effectively using the same binary) and the toolchain should check if the previous version was in that list, somehow. If you wanted to get fancy with semver, you could do stuff like `1.2.2+bin.compat.1.2.0` (meaning the binary(ies) used with a version of or higher than `1.2.0` are compatible) without violating the spec.

GiteaMirror commented

2026-04-20 09:30:01 -05:00

@huntc commented on GitHub (Nov 19, 2014):

My orininal idea was not to let 'b' be a modifier, but a variable, just like x, y and z....

Even better.

From the perspective of URL encoding though, would @ be better? e.g.

1.1.0@1 <-- Added new API, but all old API's are still compatible.
1.1.0@2 <-- A binary incompatible change to the new API, but the lib is still source compatible with 1.1.0

The other one is caused by API progression. Sometimes a new version of a library is introduced that is fully binary compatible, and somethimes a new version is not binary compatible, and requires the depending application is recompiled. This problem could be solved by using the binary compatibility indicators.

I completely agree.

I don't think it is a good idea to mix binary compatibility with version numbers. The reason is simply that binary compatibility depends on additional factors, like compilers, compiler versions, OS versions, etc. The version number should refer to the source code, imho.

The suggestion here is to have a version number make a declaration that a library's version is binary compatible with a previous version or not. Users of a library are then able to make a decision on upgrading to later versions.

I believe the expression of binary compatibility would also be entirely optional.

@huntc commented on GitHub (Nov 19, 2014): > My orininal idea was not to let 'b' be a modifier, but a variable, just like x, y and z.... Even better. From the perspective of URL encoding though, would `@` be better? e.g. ``` 1.1.0@1 <-- Added new API, but all old API's are still compatible. 1.1.0@2 <-- A binary incompatible change to the new API, but the lib is still source compatible with 1.1.0 ``` > The other one is caused by API progression. Sometimes a new version of a library is introduced that is fully binary compatible, and somethimes a new version is not binary compatible, and requires the depending application is recompiled. This problem could be solved by using the binary compatibility indicators. I completely agree. > I don't think it is a good idea to mix binary compatibility with version numbers. The reason is simply that binary compatibility depends on additional factors, like compilers, compiler versions, OS versions, etc. The version number should refer to the source code, imho. The suggestion here is to have a version number make a declaration that a library's version is binary compatible with a previous version or not. Users of a library are then able to make a decision on upgrading to later versions. I believe the expression of binary compatibility would also be entirely optional.

GiteaMirror commented

2026-04-20 09:30:02 -05:00

@LasseBlaauwbroek commented on GitHub (Nov 19, 2014):

@FichteFoll The problem adressed here is about dynamic linking. There is no toolchain involved here. The question is that if an end-user already has a library X with version 1.1.0|1 compiled and installed (because another application A depends on it) and the user want to install another application B that depends on library X version 1.0.1|1; can the already installed version be used in its place? In this case the answer is yes.

@huntc I did not think any syntactic considerations through yet. I think it is important to first specify the semantics of a binary compatibility indicator more thoroughly. But that aside, an @ sign might indeed capture the meaning of binary compatibility better (and look more appealing) than a bar ('|').

I believe the expression of binary compatibility would also be entirely optional.

I agree completely (this is also in my original proposal, at the end).

@LasseBlaauwbroek commented on GitHub (Nov 19, 2014): @FichteFoll The problem adressed here is about dynamic linking. There is no toolchain involved here. The question is that if an end-user already has a library X with version `1.1.0|1` compiled and installed (because another application A depends on it) and the user want to install another application B that depends on library X version `1.0.1|1`; can the already installed version be used in its place? In this case the answer is yes. @huntc I did not think any syntactic considerations through yet. I think it is important to first specify the semantics of a binary compatibility indicator more thoroughly. But that aside, an @ sign might indeed capture the meaning of binary compatibility better (and look more appealing) than a bar ('|'). > I believe the expression of binary compatibility would also be entirely optional. I agree completely (this is also in my original proposal, at the end).

GiteaMirror commented

2026-04-20 09:30:03 -05:00

@rlidwka commented on GitHub (Nov 22, 2014):

My point is, you cannot express binary compatibility with a version number

As far as I know, OpenSSL does exactly this.

@rlidwka commented on GitHub (Nov 22, 2014): > My point is, you cannot express binary compatibility with a version number As far as I know, OpenSSL does exactly this.

GiteaMirror commented

2026-04-20 09:30:03 -05:00

@gaborcsardi commented on GitHub (Nov 22, 2014):

My point is, you cannot express binary compatibility with a version number

As far as I know, OpenSSL does exactly this.

Where? They don't even seem to provide binaries. https://www.openssl.org/source/

@gaborcsardi commented on GitHub (Nov 22, 2014): > > My point is, you cannot express binary compatibility with a version number > > As far as I know, OpenSSL does exactly this. Where? They don't even seem to provide binaries. https://www.openssl.org/source/

GiteaMirror commented

2026-04-20 09:30:04 -05:00

@gaborcsardi commented on GitHub (Nov 22, 2014):

sometimes a new version is not binary compatible, and requires that the depending application is recompiled. This problem could be solved by using the binary compatibility indicators.

This is exactly what the version number is for. I.e. from semver.org:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,

MINOR version when you add functionality in a backwards-compatible manner, and

PATCH version when you make backwards-compatible bug fixes.

@gaborcsardi commented on GitHub (Nov 22, 2014): > sometimes a new version is not binary compatible, and requires that the depending application is recompiled. This problem could be solved by using the binary compatibility indicators. This is exactly what the version number is for. I.e. from semver.org: > Given a version number MAJOR.MINOR.PATCH, increment the: > - MAJOR version when you make incompatible API changes, > - MINOR version when you add functionality in a backwards-compatible manner, and > - PATCH version when you make backwards-compatible bug fixes.

GiteaMirror commented

2026-04-20 09:30:05 -05:00

@rlidwka commented on GitHub (Nov 22, 2014):

Where? They don't even seem to provide binaries.

See their faq. They talk about two things: binary compatibility and source compatibility. "Binary compatibility" means you can expect the program to work with version X if it was built against version Y.

It's about ABI, not API, although you can mix these things into one.

Probably meta-information like 0.1.2+b1 would be good enough for this though.

@rlidwka commented on GitHub (Nov 22, 2014): > Where? They don't even seem to provide binaries. See their [faq](https://www.openssl.org/support/faq.html#MISC8). They talk about two things: binary compatibility and source compatibility. "Binary compatibility" means you can expect the program to work with version X if it was built against version Y. It's about ABI, not API, although you can mix these things into one. Probably meta-information like `0.1.2+b1` would be good enough for this though.

GiteaMirror commented

2026-04-20 09:30:06 -05:00

@gaborcsardi commented on GitHub (Nov 22, 2014):

@rlidwka Indeed, but I think they are just talking about API changes. Essentially they have four parts instead of the semver recommended three (only, the last one is a letter), because they do not want to increase the major number every time they have an API breaking change. But other than this, they just have a single version number.

In other words, openssl 1.0.0o and 1.1.0o are not binary compatible, the last part of the version number is not for binary compatibility in itself, imo.

@gaborcsardi commented on GitHub (Nov 22, 2014): @rlidwka Indeed, but I think they are just talking about API changes. Essentially they have four parts instead of the semver recommended three (only, the last one is a letter), because they do not want to increase the major number every time they have an API breaking change. But other than this, they just have a single version number. In other words, openssl `1.0.0o` and `1.1.0o` are **not** binary compatible, the last part of the version number is not for binary compatibility in itself, imo.

GiteaMirror commented

2026-04-20 09:30:08 -05:00

@huntc commented on GitHub (Nov 22, 2014):

At Typesafe and EPFL we use version numbers to signify binary compatibility for Scala, Akka and Play. Here's our current strategy:

The scheme is major.minor.micro.

The major number is incremented if a release is subject to considerable modifications of the public API (therefore leading to important source incompatibilities).
The minor number is increased when a release is not binary compatible with the former one.
The micro number is increased if a release is backward binary compatible with the former one.

My point here is that versions indicating binary compatibility are used today, by many things. There is a definite requirement in what @LasseBlaauwbroek suggests.

@huntc commented on GitHub (Nov 22, 2014): At Typesafe and EPFL we use version numbers to signify binary compatibility for Scala, Akka and Play. Here's our current strategy: The scheme is major.minor.micro. - The major number is incremented if a release is subject to considerable modifications of the public API (therefore leading to important source incompatibilities). - The minor number is increased when a release is not binary compatible with the former one. - The micro number is increased if a release is backward binary compatible with the former one. My point here is that versions indicating binary compatibility _are_ used today, by many things. There is a definite requirement in what @LasseBlaauwbroek suggests.

GiteaMirror commented

2026-04-20 09:30:09 -05:00

@LasseBlaauwbroek commented on GitHub (Nov 23, 2014):

I think @gaborcsardi is still talking about something else than I am. You are talking about releases of binaries and how they relate (I think); I am talking about, as @rlidwka already mentioned, the ABI of a library. It is possible for the ABI of a program to change without a change of API (and vice versa), and we essentially just want a separate version indicator for the ABI, as we have for the API (for the ABI it does not make sense to have major minior and patch, I think).

@LasseBlaauwbroek commented on GitHub (Nov 23, 2014): I think @gaborcsardi is still talking about something else than I am. You are talking about releases of binaries and how they relate (I think); I am talking about, as @rlidwka already mentioned, the ABI of a library. It is possible for the ABI of a program to change without a change of API (and vice versa), and we essentially just want a separate version indicator for the ABI, as we have for the API (for the ABI it does not make sense to have major minior and patch, I think).

GiteaMirror commented

2026-04-20 09:30:09 -05:00

@gaborcsardi commented on GitHub (Nov 23, 2014):

Well, the word ABI first appeared in @huntc 's last comment, so it was hard to me to see what you mean, especially since you explicitly said

The other one is caused by API progression

:)

However, I still fail to see how the ABI is not determined by the toolchain and the platform in general, but the application. At least in most cases.

@gaborcsardi commented on GitHub (Nov 23, 2014): Well, the word ABI first appeared in @huntc 's last comment, so it was hard to me to see what you mean, especially since you explicitly said > The other one is caused by API progression :) However, I still fail to see how the ABI is not determined by the toolchain and the platform in general, but the application. At least in most cases.

GiteaMirror commented

2026-04-20 09:30:10 -05:00

@LasseBlaauwbroek commented on GitHub (Nov 23, 2014):

Well, perhaps I should have said "library evolution" instead of "API progression" or something like that. To be honest, I had forgotten for a moment the term ABI exists...

Of course the specific form/layout of the ABI is determined by the toolchain, but we assume we have a fixed toolchain. The question becomes if the binary interface of two versions of a library are compatible, so that they can interchanged during (dynamic) linkage.

@LasseBlaauwbroek commented on GitHub (Nov 23, 2014): Well, perhaps I should have said "library evolution" instead of "API progression" or something like that. To be honest, I had forgotten for a moment the term ABI exists... Of course the specific form/layout of the ABI is determined by the toolchain, but we assume we have a fixed toolchain. The question becomes if the binary interface of two versions of a library are compatible, so that they can interchanged during (dynamic) linkage.

GiteaMirror commented

2026-04-20 09:30:11 -05:00

@gaborcsardi commented on GitHub (Nov 23, 2014):

Just for my curiosity, can you give me an example where the ABI is changing, and the toolchain and platform are fixed?

@gaborcsardi commented on GitHub (Nov 23, 2014): Just for my curiosity, can you give me an example where the ABI is changing, and the toolchain and platform are fixed?

GiteaMirror commented

2026-04-20 09:30:11 -05:00

@LasseBlaauwbroek commented on GitHub (Nov 23, 2014):

I assume you mean a change in the ABI, but no change in the API?

It of course depends on the language you use (this scenario does not occur for every language I think). But for example Java, as the link in my first post explains, removing an overloaded method from a library will break binary compatibility, but the API remains the same. So in this case the application that uses the library needs to be recompiled.

@LasseBlaauwbroek commented on GitHub (Nov 23, 2014): I assume you mean a change in the ABI, but no change in the API? It of course depends on the language you use (this scenario does not occur for every language I think). But for example Java, as the link in my first post explains, removing an overloaded method from a library will break binary compatibility, but the API remains the same. So in this case the application that uses the library needs to be recompiled.

GiteaMirror commented

2026-04-20 09:30:12 -05:00

@gaborcsardi commented on GitHub (Nov 23, 2014):

I see, that's a good example indeed, thanks.

@gaborcsardi commented on GitHub (Nov 23, 2014): I see, that's a good example indeed, thanks.

GiteaMirror commented

2026-04-20 09:30:12 -05:00

@huntc commented on GitHub (Nov 23, 2014):

Another example is adding a method to a scala trait that has implementation in it can also lead to an ABI change.

We also have a build plugin to check for ABI changes: https://github.com/typesafehub/migration-manager

@huntc commented on GitHub (Nov 23, 2014): Another example is adding a method to a scala trait that has implementation in it can also lead to an ABI change. We also have a build plugin to check for ABI changes: https://github.com/typesafehub/migration-manager

GiteaMirror commented

2026-04-20 09:30:13 -05:00

@jwdonahue commented on GitHub (Dec 2, 2017):

@LasseBlaauwbroek, this seems to be yet another "what should SemVer versions formally cover?" discussions. Since there has been no action taken on this and no discussion since 2014, unless you intend to submit a PR to semver/semver.org for review, please close this issue.