search

Arnavion / k8s-openapi

Rust definitions of the resource types in the Kubernetes client API
Apache License 2.0
382 stars 40 forks source link

Question: How to determine backwards compatibility of version feature #113

Closed Ragnyll closed 2 years ago

Ragnyll commented 2 years ago

I was wondering, is there is a way to determine when the version feature could cause a breaking change from changes in the kubernetes client api?

for example: from src/lib.rs we would select a version (eg v1_23) for the kubernetes client version.

if there is a major version bump on the kubernetes client, would that also be only available in the next major version of this crate (I assume so based off the contribution guide? Or do consuming crates need to run regression tests to verify this themselves? In the same vain, what about for minor versions of the kubernetes client? the open api spec doesnt guarantee perfect backwards compatibility in minor versions.

Arnavion commented 2 years ago

Let's say k8s-openapi is at v0.100.0, and it supports Kubernetes versions v1.50 through v1.60 inclusive. Specifically it would've been generated from some particular release of each of those versions, say v1.50.10, v1.51.9, ... v1.60.17 that will be listed in the release notes. Now, after this release has been out for a while...

Situation 1: Kubernetes releases v1.60.18, and the OpenAPI spec has no changes that affect the generated code, so there will not be a new release of k8s-openapi.

Situation 2: Kubernetes releases v1.60.18, and the OpenAPI spec has changes that affect the generated code. There will be a k8s-openapi v0.101.0 release with these changes. Note that this situation is very unlikely.

Situation 3: Kubernetes releases v1.61.0. There will be a new major release of k8s-openapi, ie v0.101.0, with support for this new v1.61 line. This is because adding support for new Kubernetes version lines is semver-incompatible, since users can have code that does one thing if version > 1.55 and another thing otherwise, which may need to be reworked for 1.61. (This can be done by a build script that checks for the env var set by k8s-opeapi, or by the k8s_if_* macros; both are documented in the crate root). If there have been other breaking API changes in the codegen of other versions, they will also be a part of the v0.101.0 release.

Situation 4: Kubernetes releases v1.60.18 and the OpenAPI spec does not change. At the same time some bug is fixed that is semver-compatible with k8s-openapi v0.100.0. There will be a k8s-openapi v0.100.1 release with this change.

Situation 5: Kubernetes does not release any new versions. At the same time, there is some change made to the generated code that is not semver-compatible with k8s-openapi v0.100.0. There will be a k8s-openapi v0.101.0 release with this change.

Ragnyll commented 2 years ago

I think I understand. Thank you for clarifying.