breaking changes and semver related to the v1.70.0 release

[notnmeyer]

https://github.com/svix/svix-webhooks/releases/tag/v1.70.0 was just released and the notes mention a breaking change to "some" sdks without being explicit about which ones.

specifically this,

Libs/All: Fix name and input structure for rarely used set-transformation route
...

• Replace EndpointTransformationIn with EndpointTransformationPatch
  • In some but not all the SDKs, these have slightly different field types
• This is a breaking change, but based on server statistics this method is barely used by anybody

what is your perspective on semver and release versioning? is a breaking change not a breaking change? as a self-hosted user, i am extremely appreciative of your work, just seeking to understand so i can adapt my risk tolerance.

tl;dr, whats scary here is that this minor version bump:

• contains a breaking change
• is not specific about which SDKs contain the breaking change i believe i misunderstood this

[notnmeyer]

oh, i think i misunderstood this bit,

In some but not all the SDKs, these have slightly different field types

my first read was that this change was not applied to all SDKs, but this is saying the field types differ by SDK. right?

[svix-jplatte]

Hey! So if you want to know about general semver considerations, take a look at #1744, it was extensively discussed there.

For this change in particular:

• It's not relevant for self-hosted setups at all, because it concerns a method that calls an API that doesn't exist in the OSS version of svix
• I checked Svix cloud's access logs for requests against this API using an SDK user-agent and found very few requests, only from two pretty old versions of the SDKs; if I had seen more wide-spread usage I would have kept the broken-ish older methods around as deprecated in the affected SDKs
• All SDKs are affected because a method got renamed, plus one argument type changed - though depending on the specific SDK and details of the calling code, the upgrade path may just be changing a method name (this is what the field types thing was kinda trying to convey, but I see now that it was rather cryptic)

[notnmeyer]

amazing, i appreciate all the info!

It's not relevant for self-hosted setups at all, because it concerns a method that calls an API that doesn't exist in the OSS version of svix

is there a way to better understand what the differences are?

edit: was reading #1744 (comment),

I meant we'll never break it in minor/micro versions.

respectfully, whether it was used or not, it was still a breaking change shipped in a minor version. so im confused about how to reconcile "we'll never do this" vs. "we'll do it... carefully".

[svix-jplatte]

It's not relevant for self-hosted setups at all, because it concerns a method that calls an API that doesn't exist in the OSS version of svix

is there a way to better understand what the differences are?

Unfortunately, we don't currently have a listing of all the differences between cloud and OSS anywhere, no.

[tasn]

@notnmeyer, this is a mistake, there shouldn't have been a breaking change. I'm going to chat with @svix-jplatte and better understand it.

[svix-jplatte]

As noted by @tasn, this was actually a misstep by myself. Sorry for that! I'm working on re-adding the previous API as deprecated.

[svix-jplatte]

This has now been fixed in the latest patch release: v1.70.1.

Again, I'm really sorry for having that unnecessary breaking change in the previous version.

[tasn]

Thanks @svix-jplatte, and sorry again @notnmeyer!

We've also re-emphasized our commitment to stability internally to make sure this is not missed again.

[notnmeyer]

no sweat, i appreciate both of you very much!