Horreum Clients Release and Versioning

[lampajr]

Given that we started generating some Horreum clients [1,2] to make the interaction with the server easier, we should set and plan the release cadence for the clients as well.

The only constraint between Horreum server and Horreum clients is the Openapi spec that is auto-generated from the Horreum server build.

Here my proposal:

Release cadence

I would propose to tie the release cadence for Horreum clients to the Horreum server, at least for Major and Minor releases (but I'd do that for patch as well).

This is making the process easier as every time we release Horreum, we will also release both clients. Moreover the versions will match, thus it will be easier for users to check if a client version is compatible or not with a specific instance of Horreum server.

Versioning convention

To make things easier, if we decide to release clients every time we release the server, I would propose to use exactly the same versioning scheme, i.e., x.y.z that Horreum is currently using.

For simplicity, x.y (in the server) == x.y.0 (in the clients).

Bug fixing

For Horreum clients bug fixing, if there is no need to release another Horreum release, we can handle them separately e.g., x.y.z.W

Conclusion

In summary, with this proposal, I am suggesting to release the clients every time we release the Horreum server.
If we need an ad-hoc client release, let's add build-number in the release of the client, e.g., of Horreum is version 0.13.1 and we already have client 0.13.1, but we need a bug-fixing release, let's do as 0.13.1.1 or 0.13.1.2.

The Major.Minor.Patch will be coherent between the server and the clients.

[1] https://github.com/Hyperfoil/horreum-client-python
[2] https://github.com/Hyperfoil/horreum-client-golang

[barreiro]

Do we want to do API changes in patch releases? If not, we only need to release clients for minor releases.

In that case, the major and minor version of the client align with the server version, while the patch version refers to fixes in the client itself.

I think we ideally should have a stable API across a major release (if we ever release a new one, but that is another discussion).

[lampajr]

Do we want to do API changes in patch releases? If not, we only need to release clients for minor releases.

That's right, under the assumption that we do not change the API in patch releases we don't actually need to release the Horreum clients.

In that case, the major and minor version of the client align with the server version, while the patch version refers to fixes in the client itself.

That's the alternative approach, thanks for highlighting it.

I do not have a strong opinion between the two approaches, maybe this one could require less releases if no patches are required on clients-side.

[johnaohara]

Our current versioning system is not semver compliant, until we redefined the architecture, but we are following the rules below;
Minor Versions: we can change the API - i.e. add new/modify features
Point Releases: bug fixes/package upgrades

At the moment, the API will not change for a minor version release train. i.e. 0.13.x will remain API backwards compatible, but 0.14 will likely break compatible

When we have redefined the archittecutre, and have an API that we are confident will not fundamentally change, we can move to strictly follow semver

[johnaohara]

i think we need a seperate release train for the clients, esp where there are client bugs fixed, but in this case I am not sure that the client versioning should follow semver, because users might assume that they need to align patch versions as well.

e..g

server: 0.13.0, 0.13.1, 0.13.2

and client: 0.13.0, 0.13.1

What happened to client 0.13.2?

[lampajr]

because users might assume that they need to align patch versions as well.

yeah, that's the main reason why I was suggesting to follow the same releases of the server. This way for every server release there is a corresponding client release.

Obviously this will require an additional number when we have to do a bug fixing release for the client only, e.g.,
server: 0.13.0, 0.13.1, 0.13.2
client: 0.13.0, 0.13.1, 0.13.2

the new bug-fixing release will be 0.13.2.1 (which breaks the semver convention I think)