Skip to content

pre-1.0 stability guarantees #508

@clux

Description

@clux

based on the client library support level doc from sig api-machinery we are currently at beta and have the current stable requirements:

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

No one assigned

    Labels

    client-stablestable client requirementsdocsunclear documentation

    Type

    No type

    Projects

    Status

    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions