Decouple Language Binding Versions From Okapi Version

[Scott Phillips]

Background

Currently, the only way to release a breaking change to a language binding is to release a new version of the platform libraries. This triggers a release of every language binding, even if there are no changes. We aim to change this, since it creates a situation where we break semantic versioning for one, or all, language bindings.

Proposal

• #421

2. Okapi Language bindings can then decide which okapi native library versions they support. This allows us to identify out-of-date libraries where needed, and prompt the user to update.
3. If we release breaking language binding changes, the major version number of that wrapper is changed, in line with semantic versioning. All other languages stay as they are
4. If we release breaking okapi native library changes, we can update all language bindings just as we would today anyway.

Pros

1. More flexibility, support for semantic versioning, which our customers will expect.
2. More clarity into what our customers are actually using in the event of debugging. (add a logger function that dumps the okapi binary version)

Cons

1. Keeping track of individual language binding versions could be a hassle - that said, our current release actions will fail in the event of a version collision.
2. More "major version" releases for some languages than others, which might indicate to our customers that some languages are "better supported" than others? In reality, this is just a count of breaking changes by language.

[Scott Phillips]

Secondary Thoughts

1. This would also apply to trinsic-id/sdk, but I'd like to solve the easy problem first, then look into the hard problem.
2. Service SDK side would allow for us to support multiple major versions of the protobuf specification in the same package, thereby allowing easier deprecation and smoother transitions across schema versions.
3. Add a service endpoint that returns the current service version?

[Jan-Pieter George]

Is this something that would be fine to not be perfect at until we hit General Availability? I feel as an alpha version of the platform, it would be great to avoid this and then when we hit GA be a lot more strict about breaking changes (never without phase-out, which IMHO we should do server side by supporting old requests).
Again, my Protobuf experience isn't the greatest, but having old requests keep working for quite a long period is really needed and I'd prefer to put that complexity on the server.

[Scott Phillips]

Is this something that would be fine to not be perfect at until we hit General Availability? I feel as an alpha version of the platform, it would be great to avoid this and then when we hit GA be a lot more strict about breaking changes (never without phase-out, which IMHO we should do server side by supporting old requests). Again, my Protobuf experience isn't the greatest, but having old requests keep working for quite a long period is really needed and I'd prefer to put that complexity on the server.

In general, agreed. Those points are mostly applicable to the services side, not the okapi side.

[Tomislav Markovski]

Not a priority before GA.

Are there any examples out there how others have managed versioning and wrapper compatibility?

[Scott Phillips]

Not a priority before GA.

Are there any examples out there how others have managed versioning and wrapper compatibility?

Not that I've specifically seen. In most cases, the wrapper package just attempts to wrap a given DLL, and fails if it can't. There isn't a tight coupling between the wrapper and the native library.

My primary concern for this is things like security bumps on the oberon library. We need a way to tell our customers that their native binary is out of date, beyond just authentication failures.

[Scott Phillips]

Let me add the okapi_version() function so that we can get the native library version in the language wrappers. We can decide on a release strategy later.