Semantic Versioning?

[olix0r]

I've read #1688, and I'd like to better understand the current state of API stability. I understand that this decision was motivated by the optics of having an 0.100.0 release, but it seems to me that is flatly at odds Cargo's use of semantic versioning.

I.e. it should be possible for an application to express a dependency on:

# Package A
[dependencies]
kube = "1.0"  # meaning `>=1.0.0,<2.0.0`

# Package B
[dependencies]
kube = "1.1"  # meaning `>=1.1.0,<2.0.0

But this is not possible, due to the public API dependency on k8s-openapi, which still breaks semver on every single release! kube 1.0 is not forward compatible with all versions

To properly express version constraints on a kube dependency, a dependency must explicitly set a max version:

# Package A
[dependencies]
kube = ">=1.0.0,<1.1.0"

# Package B
[dependencies]
kube = ">=1.1.0,<1.2.0"

I think the "correct" (from a SemVer and Cargo compatibility point of view) is to publish a new major version any time any of its unstable public API dependencies (i.e., k8s-openapi, rustls?, etc) change minor versions. I.e. kube should publish a 2.0.0 on the next k8s-openapi bump, and a 3.0.0 on the subsequent, etc... This would at least integrate properly with Cargo's dependency resolution.

While I definitely appreciate that kube's APIs are stabilizing, I'd like to advocate strongly for proper integration with the dependency management tools. As a downstream maintainer, this misalignment can be a major source of friction and frustration -- our automations need to special-case (exclude) kube libraries since they do not adhere to the rules of the road.

What is your appetite for this sort of thing?

[nightkr]

I think the "correct" (from a SemVer and Cargo compatibility point of view) is to publish a new major version any time any of its unstable public API dependencies (i.e., k8s-openapi, rustls?, etc) change minor versions. I.e. kube should publish a 2.0.0 on the next k8s-openapi bump, and a 3.0.0 on the subsequent, etc...

Yeah, I talked about this in private with @clux before 1.0. This would be the way to go; going forward, every K8s release will have a corresponding major bump, with breaking changes in kube-rs deferred until then. The 1.0 release note also says the same thing.

While I definitely appreciate that kube's APIs are stabilizing, I'd like to advocate strongly for proper integration with the dependency management tools. As a downstream maintainer, this misalignment can be a major source of friction and frustration -- our automations need to special-case (exclude) kube libraries since they do not adhere to the rules of the road.

Absolutely. Especially in Cargo, since other Cargo features also depend on semver (for example: parallel library dependencies only work between semver-incompatible release tracks).

[clux]

Indeed, this is the plan. We don't want do undermine semver.

You should be able to pin kube = 1 and not get breaking changes. I am hoping we can contain breaking changes to Kubernetes cycles, but we will see how awkward this becomes. I think our saving grace is that not that many of our dependencies are "peer dependencies", i.e. deps that force you to upgrade kube at the same time as dependency X. Because these give us perhaps the biggest problems with delaying releases of breaking changes; people get confused when latest kube is not up-to-date with the ecosystem, and we act as a drag on dependency upgrades).

• k8s-openapi obviously is a peer dep (hence why i always tried to release within a day of it releasing lest issues comes pouring in).
• schemars is a peer dep if you depend on custom resources.

Others may also be in some sense, but you are less likely to encounter them unless you are in a specialized case. Even rustls can exist with multiple versions.

Still, not upgrading any of these can still be seen as slowing down the ecosystem. So maybe we will need some supplemental majors as well.. Like right now, we can hold back releasing a breaking version for schemars 1 confusion or wait until Kubernetes 1.34 (~2mo time). We have not really codified this yet.

---

..perhaps I should have kept the bit about optics out of the issue because we are kind of trading one bad optics situation (large minor number) for another (large major number). But the benefit of it is that it allows releases like 1.1.0 to not be classified as semver breaking (which wouldn't be true at 0.X where minors are breaking)

[olix0r]

@clux Thanks for clarification!

In the fullness of time--i.e. after we've got a few of these releases under the belt--it might be helpful to elaborate on this stability plan in the README.

Congrats on the v1 milestone! 🎉