This, this, and a hundred more times this.
Incompatible is incompatible. There is no "kinda incompatible", "99% compatible" - when it comes to dependencies, they either work properly or they don't.
Software should be eternal. Without being strict about semantic versioning, it is impossible to make it so.
I can change one part of an API and leave another untouched - that's part compatible, part incompatible. It's only an issue if you used the changed part.
(If you think that first one always counts... what if the changed part is literally called YouMustNotUseThisFunctionOrYourCodeWillAlwaysBreak() ? It's clearly implied to not be part of your intended API, despite technically being part of it.)
I can add something to a type, in a way that's backwards compatible at compile time... but common reflection patterns might cause everyone's code to explode.
I can make a change that solves a bug that someone was accidentally relying on by doing the wrong thing, but doesn't affect compile-time behavior, nor runtime for anyone using the library the way they should. But that bug-user's code is now broken, is this an incompatible change?
There is even a "law" for that: https://www.hyrumslaw.com/
When you commit to a version 1, you assume that every user of the package is using every feature you provide through your official API. If you break any slightest piece of the API, you've broken compatibility. It might "kinda work" for many users, but it will almost surely cause significant pain for many others.
> I can make a change that solves a bug that someone was accidentally relying on by doing the wrong thing, but doesn't affect compile-time behavior, nor runtime for anyone using the library the way they should. But that bug-user's code is now broken, is this an incompatible change?
It is not an incompatible change, and it is the responsibility of the bug-user's code to fix the bug in his program.
Of course, when such a thing happens on a large-enough scale, the API developer sometimes cannot afford to "fix" the behavior and force countless users to fix their programs, so the quirk just becomes de-facto part of the API.
Semver doesn't force you to do anything. You can stay on v0 forever for all it cares, or you can bump a major version every day.
What semver doesn't allow you to do is lie to your users.
That is not how semver works. If you read the documentation [0], it says right there that the public API must be clearly defined but that can also happen through documentation and you only have to up the major version if you break that specified public API.
You can certainly consider it bad programming practice to expose something via the means of the language that is not defined as public API but it is not against semver to do so.
[0]: https://semver.org/
if hash(libpath) != predefinedHash {
log.Fatal("broken compatibility teehee")
}
If that is what you meant with "official API" then we are on the same page.
And that's not something to accept and work around, but a problem, one that Go's hard stance solves.
An HTTP server can remain API compatible, and still drop or break support for a major feature you care about. Surely you don't want that to ship in a patch release.
Adding a new struct field, even a private one, can break API compatibility in Go if people use your struct without named fields. Do you want a new library in this case or not?
Semver doesn't cover CLI compatibility, either, do you want a CLI redesign to remain v1 or become v2?
Nuance matters. Stating to "just be strict about semantic versioning" doesn't help, semver is fuzzy.
If a change results in user programs breaking, it's a bug in the
kernel. We never EVER blame the user programs.Even in the Linux example, kernel modules do not receive compatibility guarantees because it is difficult to keep. You may need to rewrite your module depending on how it is written when upgrading the kernel. It also doesn't apply in case of security vulnerabilities and certain classes of bugs. Technically viruses can be user programs which rely on those vulnerabilities and even excluding those, there are cases where some API seems benign but later turns out to be flawed (like precise timers in the context of browsers).
I define it as "provides the equivalent API".
Other than that, I don't understand your question. What does "use the same method signature but with different meaning" mean? What is my "duck typing code"? Is duck typing part of your API?
You may say "Well, don't do that," but it seems like golang users think of this as a way to provide backwards-compatible API upgrades[0].
> What does "use the same method signature but with different meaning" mean?
.draw(times: int)
> What is my "duck typing code"?
You collect everything with the draw signature as options to draw with.
> Is duck typing part of your API?
What do you mean “your API?”. Maybe I mention it in the docs, maybe I don’t. But that doesn’t really matter because if we’re going to compare intent, then this is subjective. And it really doesn’t matter because duck typing isn’t part of an API, it’s a technique / language feature. By just adding a method, I removed your ability to do something.
My point with all this is your definition is lacking. You just shifted the pain of defining “breaking change” to the pain of defining “compatible API”. Which is fine if you’re then going to define that strictly (see Hickey’s talk on SemVer), but you haven’t.
1) Machine-readable definitions of the functions and data types used
2) Human-readable explanation of what the previously defined functions do when passed each of the allowed data types, with a high-level explanation of how is the API supposed to be used.
The first part is usually implemented as part of your programming language - in case of Python, type hints can be used as a substitution.
The second part is necessarily informal, since it targets humans. But that does not mean it cannot be well-defined. For example:
mmap() creates a new mapping in the virtual address space of the calling process. The starting address for the new mapping is specified in addr. The length argument specifies the length of the mapping (which must be greater than 0).
It's simple: a user inherits from your class and adds a method to their user-defined subclass. You then ship a new version of your library that adds a method with the same name to your class, but with different semantics, and other parts of your library call this method expecting it to have the semantics you defined. You've just broken the user's code, even though you say this was a "backwards-compatible" release, and it isn't the user's fault because they were using your library as it was documented.
https://stackoverflow.com/questions/1456785/a-definitive-gui...
That's why I prefer ComVer: https://gitlab.com/staltz/comver
For example, assume that you're using a dependency, libparser, v1.0, which uses ComVer. In version v1.1 they add a new function, foo() which does something that you want. However, at the time of you writing the software, the latest version was v1.2, which you use because you're a good engineer who likes to keep things up-to-date.
Now think about what happens when you distribute your application to three people:
- person 1 has libparser v1.0 - you program can't work, because v1.0 doesn't have foo(), so you obviously must require minor version that your program was built with - which is v1.2
- person 2 has libparser v1.2 or higher - you program works.
- person 3 has libparser v1.1 - you program CAN work, since v1.1 contains foo(), but it WILL NOT work, because your application requires at least v1.2.
Now, you might say, "well a developer should know that foo() was added in v1.1 and pin that as the lowest required vesion" - in which case I reply that ComVer doesn't help you a tiniest bit with this, because both API extensions and bugfixes are mashed together into a minor version, so now you have an order of magnitude more changelogs to go through.
SemVer stricly separates API extensions and bugfixes so you can just browse the minor version changelogs and see which version added the feature you require.
> Without being strict about semantic versioning, it is impossible to make it so.
There is no semantic versioning if you're that strict. You have to update the major version on every single release, no matter the contents, if your idea of backwards compatibility is that absolute.
Let me give you a concrete example: I have a go package with this code:
var ErrBadThing = errors.New("somthing bad happened")
func DoThing() error { /* maybe return ErrBadThing */ }
The answer is "it depends"
err := mypkg.DoThing()
if errors.Is(err, mypkg.ErrBadThing) { /* will still work after change */ }
if strings.Contains(err.Error(), "somthing") { /* will no longer work after change */ }
If you argue that is a breaking change, well, what about adding a new method, which breaks reflection (like 'reflect.NumMethod()' returns one more, so if someone relied on indexing into your methods with reflection, you broke em!)? What about someone downstream applying a "patch" to your code before compiling it? Any change can break that.
The go authors have taken a much less strict approach. Go is still semantically "v1", but they've made a ton of breaking changes, from making `net/http` silently switch to http/2, to changing the semantics of various tls and security related functions, etc etc.
This is an inevitable consequence of Hyrum's Law[0]. It's been observed before but I find Hyrum's Law a very good and concise summary of the problem.
If your API only specifies that AN ERROR is returned, then it's a bug in the user code to rely on an implementation detail.
If you want your software to be pristine forever, you really need to pin your dependencies, ideally via copying the source of the library into your repo so you aren't reliant on a package manager being available in the future. For library developers, regardless of versioning scheme you need to avoid ANY breaking changes whatsoever. Instead of changing an existing function, introduce a new one so that your downstream users can still access the old behavior while keeping up to date. Trust me when I say this will be much easier most of the time than patching old versions with security updates and bug fixes.
At least for typed languages where an incompatibility clearly caught at compile time is usually preferable over a murky "technically it's still the same API, but..." I'd rather have separate numbers for major incompatibility/minor incompatibility.
If you don't want to freeze your API, then just use 0.X.Y, everyone will understand that they need to do regular maintenance if they want to use your code.
But please, I beg you, do not use version 1+ if you're not planning to keep the compatibility promise.
Edit: Apparently this is wrong! See replies below.
[1]: https://fasterthanli.me/articles/abstracting-away-correctnes...
I just looked at the Git history and this is plain false. It already looked that way when the big source tree move (src/pkg/ -> src/) was done in 2014. Tracing it back further (to before Go 1.0 times, when there wasn't even a builtin error interface yet and the function returned os.Error), ImportedLibraries was *never* implemented in debug/pe.
1. go 1.9 adding monotonic clock readings in a breaking way, i.e. this program changed output from 1.8 to 1.9: https://go.dev/play/p/Mi6cGCPd0rS
2. net/http started defaulting to http/2 for the same methods, an obviously breaking change
3. go1.17 switched to silently truncating a lot of query strings https://go.dev/play/p/azODBvkb-zK
4. Check out 'PreferServerCipherSuites' on tls.Config. https://pkg.go.dev/crypto/tls#Config ; of course that was a breaking change.
There's a few other things like this littered throughout the go stdlib, and I've personally hit far more breaking changes in Go's stdlib than the "go 1 compatibility promise" would have you expect.
That's not a breaking change, if you were comparing Times with just "==" before 1.9, your program was broken as well:
From the 1.8 source [1]:
// Equal reports whether t and u represent the same time instant.
// Two times can be equal even if they are in different locations.
// For example, 6:00 +0200 CEST and 4:00 UTC are Equal.
// Do not use == with Time values.
func (t Time) Equal(u Time) bool {
return t.sec == u.sec && t.nsec == u.nsec
}
There are many cases where you know that your times are in the same timezone, or you don't mind different timezones comparing as different, and so '==' used to work correctly quite often.
My program was clearly not broken in 1.7, when I followed the documentation "Equal ignores location, == uses location", and things worked well.
My program became counter to their documentation in 1.8. My program broke in 1.9.
I don't see how that is not a breaking change.
It seems to me like a flaw in the language that "==" can compare unexported struct fields.
Looks like it's possible to disallow comparing structs with "==" at compile time: https://go.dev/play/p/BfM6sDxlTq9. Not ideal, but better than nothing I suppose.
But of course, then such structs cannot be used as map keys: https://go.dev/play/p/JXzqHPInJ-G.
For downstream consumers that gives 2 options: get stuck on an old version silently sometimes, or deal with an occasional breakage during usual dependencies updates. If the old version is used for talking to some external service, you will break one day.
However, in case that two versions are so incompatible that both sides of communication channel need to update, then I think it's fair to place responsibility on the service writers to notify their users (through deprecation warnings, documentation, chat, etc.) of the change.