Follow SemVer conventions

[eberle1080]

Bug Report

Version

(golang)

github.com/svix/svix-webhooks v1.58.1

Platform

Various (MacOS, Linux x64 mostly)

Description

My team uses dependabot on GitHub to keep up with releases. It has been a recurring theme that minor version increases result in breaking api changes. This can be things like pointer params becoming non-pointer (and vice versa), structs being renamed, packages being relocated, functions being renamed, etc.

This is surprising behavior, because a minor version bump shouldn't be breaking, at least if you're following SemVer conventions. We have concerns about continuing to rely on the go sdk due to stability. If the minor version can break on a whim, that's not a dependency we want to rely on.

Please follow SemVer conventions: https://semver.org/

[tasn]

Hi @eberle1080, thanks for reaching out, and sorry for the trouble this has caused.

We follow a slightly modified semver for the SDKs. We don't break API as a rule (and if we ever will, we'll bump a major version) except for when breaking the API fixes a bug (as in: the API should never have been what it was, it was a mistake) and the fixes are extremely simple (you can add a * or a & or something like that to fix it). We won't break things in ways that change behavior or force you to make more difficult decisions than just fixing compilation errors. We don't make changes that change behavior or break in ways not caught by the compiler. Though when does happen, they may happen in a minor version upgrade (not micro).
This only applies to the SDKs, the HTTP API is not changing even if fixing bugs as that will actually break integrations (rather than being annoying when updating a version).

I know this is suboptimal, I really wish we didn't have to do it, but it's much better than the alternative. Consider the case of a parameter not being nullable even though the server supports it. That's actually a very legal (and often used) value for some things. If the Go SDK doesn't allow that people can't use it. It's not really a "major" change that requires people to read the docs, and make significant changes, it's just a case of fixing the compilation times.
The above was about a mistake, but consider a more innocent example: adding a new field to MessageIn or ApplicationIn. This too will cause compilation errors until you set the new field to null. It could potentially be avoided by following a builder pattern, but that sucks compared to using struct initializers. So even if we don't make any changes the small (easy to fix) compilation errors will happen in the SDKs.

We really hate making any changes at all, and in fact, I believe we broke the Go SDK for the last time, having cleaned all of the remaining issues that people complained about with he Go SDKs (for example, not being able to set nulls to some fields, or Patch endpoints not working as expected).

I understand from your message that we are eroding your trust with these changes, and that was not the intention. I'd love to know what you think about the above, and if you have any better ideas.

Thanks, and sorry again!