-
-
Notifications
You must be signed in to change notification settings - Fork 356
Description
based on the client library support level doc from sig api-machinery we are currently at beta
and have the current stable
requirements:
- support level documented per-platform
- Library documentation - yes, via
#[deny(missing_docs)]
: https://github.com/clux/kube-rs/blob/38caa6beee3c7a12fc7bd46a5357e1258196cfca/kube/src/lib.rs#L74 - Deprecation policy (backwards compatibility guarantees documented)
- How fast may the interface change?
- Release process well documented - yes, release.toml describes procedure, linked to in 38caa6b
- Versioning procedure well documented - one liner in about pre-1.0 semver strategy 38caa6b
- N documented users of the library - we could link to many: Stackable (all their operators) + Microsoft (krustlet, krator), logdna agent, rlink-rs, kubeapps proxy, perhaps also company concepts like h2oai + ephemeron, and perhaps cli tools like kdash - took a small subset in d8b42c7
Some key questions and observations:
how do we define how fast interfaces change?
obviously at post 1.0 we can deprecate fully, and parallel introduce features. but pre-1.0, things do change.
is there value in quantifying this? i know people will kind of look at these documents and use it as empty justifications to companies that's basically "hey, look, dd!". i joke, but like, how much value is there in saying "at most 2 breaking changes per release" other than it encouraging smaller releases (and we release pretty frequently in general). Maybe there are better ways to describe this?
deprecation policies
pre 1.0 i feel we can do a best effort to not break things, and where possible have deprecated functions available for at least 6 months. of course this won't always be possible yet; we don't have full feature parity with go, and the better design choices are not always clear. in those cases, we will denote changes as BREAKING
in CHANGELOG.md
and users can do changes at their own will through version pinning with cargo.
Per platform support
Well, we can document that we support Linux, and that everything else might require feedback for subtle issues. Windows / Mac are to some degree relying on strength-in-numbers atm because CI for these is in general not free.
What about Arm? We don't build for that here, but big community of tinkerers that try to build lightweight stuff on k3s.
definition of stability
an interesting consequence worth noting here:
because of the requirements in the linked document, we can have the kubernetes: stable
badge even before our 1.0 release because it doesn't require us to never break things, it just requires us documenting our procedures/policies for breaking changes. Honestly, I think that's a pretty nice approach, even if it might look a bit strange to people seeing a stable badge on a pre-1.0 crate.
as a side-note following CloudNativeRustDay: people already consider us mature from many shoutouts and this on twitter: https://twitter.com/JamesLaverack/status/1389326493180903427
Metadata
Metadata
Assignees
Labels
Type
Projects
Status