What do to about versioning

[rurounijones]

This issue is all about versioning and how we want to handle it.

Background

gRPC is designed with the philosophy that you maintain backwards compatibility as much as possible and that, when you cannot, you provide a new API while maintaining the old API (at least until you are sure everyone has migrated).

Therefore we need to think about how we will handle this in DCS-gRPC

Options

Embrace versioning throughout the stack

To this end the recommended (and kind of required by Java and Go clients apparently) namespace format is. package.version so, for example. Our atmosphere package should actually be atmosphere.v1 and if we ever add a breaking change to any of the APIs then we add an atmosphere.v2 package and clone the .proto and make our changes in the new proto. (This is also reflected in the folder structure).

However if we completely embraces this concept then we need to do two things.

1. Update the rust to become version aware (I am not sure if this requires extra rust code or if we just need to add the versioned services for example).
2. Make all of our Lua code follow this same versioning pattern which would result in something like GRPC["methods"]["atmosphere"]["v1"]["getWind"] = function ... and mirroring the proto folder structure in that respect.

The issue with this is that we would end up loading all of the different versions of lua into the scripting environment which kind of goes against our concept of "more performance" but I am not sure if loaded but unexecuted lua is actually that much of a problem. There might be issues with streaming if there are streams coming from two different versions and we are trying to optimised but that scenario might not happen (Or we can make streams the exception in that we will only support 1 version at a time).

Only update version if the interface changes

We only create a new version if we change the public interface. Changes to the lua implementation will not prompt a version upgrade requirement. This allows us to always have just one implementation of lua instead of multiple versions.

No versioning

We do not do any gRPC / code versioning and rely on semantic versioning to allow clients to decide if they want to upgrade their servers and clients. I did this with the demo apps and, with the help of an IDE admittedly, it wasn't that painful.

An option I have missed?

???

Final thoughts

I am not actually against any of the above options. I think the full versioning option is the proper option if we think we will have many different clients (which is actually a hope of mine so that adds weight to this argument).

Otherwise I think we should just go with no versioning. I think the "interface change only" option brings extra complexity without any appropriate benefit.

No matter what options we choose I think we need to do the v1 package naming to make things easier for Go and Java clients anyway and I think we should do it now since we are making big refactoring changes anyway.

[rkusa]

If we achieve adoption of the gRPC server where other mods start to depend on it, I see versioning getting to be an important part. So'd totally up for v1 of services once we are happy with the API. Maybe we can still leave us the following options:

• v0 services can have breaking changes without a major version increase of the gRPC server
• old version can be removed with a breaking change release (major version) of the gRPC server

The latter might be something we could reserve us to pair with some bigger version increases of DCS, e.g. when going from 2.7.* to 3.0.*, or maybe also from 2.7.* to 2.8.*.

[rurounijones]

Could you clarify if you are going for the "Full versioning" with version namespaced lua as well? Or something else? I think starting at a v0 is fine while we are working on the APIs. there might be some that are so stable and unlikely to change that we would be comfortable with having them as v1 immediately (the trigger stuff for example is very minimal)

[rkusa]

I'd try to avoid duplicating the Lua stuff as much as possible. E.g. if getWind didn't change I'd move it to GRPC["methods"]["atmosphere"]["v1"]["getWind"] and have both the v0 and v1 gRPC services call the v1 variant. If a method changed, I'd keep it in both v0 and v1.

I don't have a strong opinion on whether we should go for Lua namespaces or a simple prefix (ala getWindV1).

[b1naryth1ef]

I honestly wouldn't expect a breaking change for a while, so my guess is this could potentially be deferred until that point. From a client perspective I don't see adding the version to the namespace now as making anything easier in the future (e.g. adding it later during a breaking change would be the same flow as a regular breaking change), but I guess from a locking down a v1 standpoint that may be nice for some end-users.

An advantage of using semver on rust-server is that non-breaking changes to the protos will over-time accumulate and add up to a bunch of if-guarded support-based behavior in the luas/server implementation. Cleaning up the support for deprecated things could just involve removing them and bumping the version of rust-server, which downstream may not require any changes (if you where not using any of the deprecated fields/methods/structures). This would be significantly cleaner than a full proto version bump which would re-namespace a lot of things causing a noisy diff in libraries as imports are shuffled. Realistically I have no clue how many deprecated fields/etc we'd end up with, DCS scripting itself isn't really a fast-moving surface from what I've seen, but it would at least provide additional flexibility.

[rurounijones]

I honestly wouldn't expect a breaking change for a while, so my guess is this could potentially be deferred until that point.

We already have breaking changes between 0.1.0 and the next release as we re-jiggered all the of API organisation and namespacing a we learn the best ways to do things in gRPC. That is the main concern here rather than the underlying DCS APIs changing.