controller-runtime versioning

[joelanford]

At the community meeting on 9/11/2019, there was a discussion about how to version controller-runtime to handle scenarios around dependency changes:

• How to handle breaking changes in controller-runtime APIs introduced by controller-runtime contributors or by breaking changes in dependencies (e.g. k8s.io/client-go)
• How to handle no breaking changes in controller-runtime APIs but possible user-facing breaking changes due to upgrades of controller-runtime's transitive dependencies
• Can we backport fixes to versions of controller-runtime that support older versions of Kubernetes?

My understanding of semver is that we need to only consider the first scenario when choosing a version number after dependency changes.

My two cents - if the controller-runtime API changes are backwards-compatible, I'm not sure it makes sense to try to ALSO consider compatibility of all transitive dependencies -- that's what the version numbers of the transitive dependencies are for.

If we want to be helpful, we could add a statement to the release notes when we update dependencies to let users know that they might require code changes if they're using those dependencies directly.

With these scenarios in mind, I'd propose a slight change to the versioning scheme while we're pre-1.0:

• Bump the minor version when we add features, make breaking changes, and/or update Kubernetes versions to a new minor version (e.g. go from 1.14 to 1.15)
• Bump the patch version only for patches, backports, etc.

post-1.0, I would propose:

• Bump the major version when breaking changes are introduced in controller-runtime APIs
• Bump the minor version when we add backwards-compatible changes or make backwards compatible dependency updates, where we consider only controller-runtime API compatibility.
• Bump the patch version only for patches, backports, etc.

Thoughts?

/cc @DirectXMan12 @shawn-hurley @justinsb @droot

[shawn-hurley]

How to handle breaking changes in controller-runtime APIs introduced by controller-runtime contributors or by breaking changes in dependencies (e.g. k8s.io/client-go)

There was the potential talk of a generic library that does not depend on k8s.io/api or k8s.io/apimachinery in the apimachinery sig meeting. I would like to explore if we could either help with this work or do this work? I think this would be very helpful for everyone. @DirectXMan12 Have you seen anything more about this?

This would allow us to not have to follow kubernetes release IIUC and allow this library and others to have their own release's. We may still want a compatibility matrix if something drastically changes in the underlying library but I think this might be the place to spend our cycles?

What do folks think?

[DirectXMan12]

I haven't seen anything more yet, but I would like to help out with that effort. I think @deads2k was the one that brought it up. @sttts and I have talked about it in the past before

[sttts]

@deads2k is preparing a KEP for this effort.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[DirectXMan12]

/lifecycle frozen