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