[Inquiry] Client library versioning

[marcind]

Inquiry

I wanted to start a discussion about client versioning. Taking the Go implementation, it is still in "Public Preview". At the same time due to how Go module versioning works, it's also at v1 and has shipped a number of point releases.

A developer could do go get github.com/valkey-io/valkey-glide/[email protected] to get the current release and be forgiven for assuming that the client they are getting is fairly mature and when they upgrade to v1.4.0 or later they should not expect breaking changes. But given the preview status, they are likely to be wrong.

Has this been considered? What versioning strategy is the project following? (SemVer?)

Is Go GA not going to happen until Glide 2.0? (at which point github.com/valkey-io/valkey-glide/go/v2 will become the true first version of the client)

Will all the various language versions be released in lock-step? If a breaking change is required in some other language, will the Go client be bumped to v3? Conversely, if the Go client requires a breaking change will that be delayed until the big 3.0 release?

Would it make sense to separate the versioning of each client from the versioning of the Rust driver and allow the clients' public API to evolve independently of how they use the driver?

Language

Go, others

Language Version

No response

Engine Version

No response

Operating System

No response

Additional Technical Information

No response

[avifenesh]

@marcind Would you be fine with me converting it into a discussion? I feel it would fit better
Additionally, not regarding this topic, would you mind joining us on valkey slack? I think we could benefit from your observation a lot, and include you, if you like, in the go client discussions.

For your question, while there is a place to discuss further, and it was discussed in the past few times, we accumulate breaking changes from all languages, and we release all together in one major.
In the go case, since there is no way to have a pre-stable version, we would release it as GA under 2.0, for all the clients.
While most of the clients won't have any breaking changes, we would introduce mild breaking changes to java, and while not exactly user-facing API, node will have a different structure, so might affect bundling and similar. So all of those will be out together with GO GA, as a point of putting all what we need to change which might impact users.

We generally avoid breaking, and we consider heavily the API design for avoiding breaking (see context.context for an example of considering changes in the development timeline, in order not release what we consider as a possible change for the future).

As said, that was brought up in discussions many times, and there are some different opinions. The current status is that all bumping together, but with the growth of the project, I do believe there's a place for discussing it again.

[jbrinkman]

This really is a philosophical question. Are we versioning the project or are we versioning individual packages? There are pros and cons to each approach. At this point, since all packages exist in a single monorepo, the version number applies to all packages. even though some language wrappers are more mature than others. CPP, Ruby, .Net and whatever other wrappers are created, will all live in a world where they never had a 1.x version. In the case of Go, while the wrapper itself may be a 1.0 level of maturity, Glide-Core, written in Rust, which is part of the Go package, will actually be much more mature than that. How do you properly indicate with a single version number the maturity of the whole package which includes both new code, as well as older code. I have been on other open source projects which took the same approach of versioning the whole project rather than trying to manage versions of individual components.