Document policy guidelines on core dependency & tooling versions

[ncdc]

User Story

As a developer, I would like to understand when it's appropriate for this project to upgrade versions of its core dependency and tooling versions.

Detailed Description

We rely on several core dependencies and tools for this project to function properly. These include:

• controller-runtime
• controller-tools
• kubebuilder
• client-go
• apimachinery
• kustomize

We have a recent open pull request (#1812) to upgrade controller-runtime to v0.4.0 and client-go to kubernetes-1.16.0. The motivation is that kubebuilder v2.2.0 creates scaffolded projects that use these versions of controller-runtime and client-go, and because cluster-api's go.mod has older versions of these two dependencies, there is an issue.

I'd like us to come up with guidelines around the versions we use and expect, and when it's appropriate for cluster-api to upgrade to newer versions.

/kind documentation

[vincepri]

We should definitely try to document all of these in the go.mod file as a comment on top of the require dependencies.

I'd also add that we need a policy around go versions.

[detiber]

We should definitely try to document all of these in the go.mod file as a comment on top of the require dependencies.

It was my understanding that the go tooling does not necessarily respect/retain comments in the go.mod file. Has the policy for that changed?

[vincepri]

You can leave and save comment around the require block, not inline though

[detiber]

I'd like to see us have a pretty strict policy around updating these (as well as the go version) for release branches, however I'm not sure we need or really want much restriction here for vNext. Opting instead to be more mindful of the user/operator facing changes for vNext instead (minimum k8s version required, for example)

[ncdc]

I agree that the release branches need to be severely strict.

For master, we can advance more rapidly. It might be nice to run an e2e test against a PR that bumps dependencies before we merge it.

Another thing to consider: if someone is using kubebuilder to add new APIs to this project, that's an area where I'd like to see consistency (although I don't know how we enforce that).

[vincepri]

A lot of the dependencies listed in the original post are related to controller-runtime.

What if we target a minimum Kubernetes version for the management cluster and pick the correct dependencies accordingly?

[ncdc]

That works for me. Want me to open a PR with some draft language?

[vincepri]

Sure that works for me, we can revisit the minimum management cluster Kubernetes version at the start of each cycle, release notes for vNext should then include language that informs users of the new breaking changes.

[detiber]

One thing to note is that the minimum version of kubernetes to support for the management cluster is not the same as the versions of transitive kubernetes dependencies imported.

[ncdc]

Thinking about this more, the breaking changes section in the contributing guide covers this.
/close