docs: document branching strategy #1515
Conversation
k8s-ci-robot
added
the
do-not-merge/release-note-label-needed
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: justinsb The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
cncf-cla: yes
k8s-ci-robot
added
approved
✅ Deploy Preview for kubernetes-sigs-cluster-api-gcp ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
k8s-ci-robot
added
release-note-none
|
This has come up a few times now, I figure I would write down a strawman. cc @cpanato |
| Feature development happens on the `main` branch, and [nightlies](nightlies.md) are released from the `main` branch also. | ||
| While we aim to keep the `main` branch healthy, it is intended for development and testing, and should not be used in production. | ||
|
|
||
| As such, we will aim to keep the main branch up to date with the latest versions of all dependencies (go toolchain, CAPI, other go module dependencies). |
There was a problem hiding this comment.
I think this is right, we should basically auto-bump everything on main
There was a problem hiding this comment.
I think we mostly already do with the dependabot setup we have. Of course we have some constraints as CAPI is normally couple with one specific k8s version and one specific go version, and we try and keep that the same in CAPI providers
There was a problem hiding this comment.
Agreed, I'm hoping we can write down our intent and then use it for automation - both on doing the bumps and perhaps on reviewing PRs. It comes up in particular on go version bumps: I think that on the main branch we should bump go toolchains automatically, to the latest, even if that puts us onto a new minor or ahead of CAPI. Sometimes there will be e.g. new go vet primitives and the PR won't merge without other changes, sometimes we might find a go regression (in theory).
I can see an alternative strategy where we bump main to the latest patch versions within a minor, matching CAPI on the minor. (And for any libraries which aren't in CAPI, like say a GCP library we do bump minors). I think that would work as well: CAPI is pretty prompt at bumping.
There was a problem hiding this comment.
I think I covered this in #1515 (comment)
I'd personally strive to follow CAPI as close as possible.
Also I am happy with
strategy where we bump main to the latest patch versions within a minor, matching CAPI on the minor. (And for any libraries which aren't in CAPI, like say a GCP library we do bump minors). I think that would work as well: CAPI is pretty prompt at bumping
There was a problem hiding this comment.
CAPI ~ follows its k8s dependency regarding to the go version. This does not mean a provider has to.
Note: If the Go minor version of one of our supported branches goes out of support, we should consider bumping to a newer Go minor version according to our backport policy. Usually this is done after k/k bumps the Go version in their release branches.
The right Go minor version for a Cluster API branch can be looked up as follows (based on an example):
Cluster API v1.10 has Kubernetes v1.32 as a dependency: https://github.com/kubernetes-sigs/cluster-api/blob/v1.10.0/go.mod
Kubernetes v1.32 uses Go 1.23.8 (can be seen by checking the corresponding kubekins image in https://github.com/kubernetes/test-infra/blob/1a5662a/images/kubekins-e2e-v2/variants.yaml#L19)
=> Cluster API v1.10 can be bumped to Go 1.23
There was a problem hiding this comment.
Thanks for the detail @chrischdi
Good to know it is not a mandatory requirement 😄
I'd still like to see them going hand in hand with respect to that, to avoid unwanted incompatibilities and surprises 😬
|
|
||
| As such, we will aim to keep the main branch up to date with the latest versions of all dependencies (go toolchain, CAPI, other go module dependencies). | ||
|
|
||
| Release branches lock to a particular minor version of CAPI, but will update other dependencies on these branches while they are supported. |
There was a problem hiding this comment.
It sounds like we have not updated go versions on existing branches, but I think we should
There was a problem hiding this comment.
You mean patch level Go version bumps right?
There was a problem hiding this comment.
So I think it is something we should decide. I think we want to be running a supported version of golang at all times, and I think we want to bump minors if our minor is no longer supported.
Should we say something like "for the go toolchain, we will bump to the latest supported patch within the same minor; we will bump to the latest minor if our minor goes unsupported.
(I've realized I can also say "particular minor version of CAPI - and thus of kubernetes dependencies including controller-runtime")
It might be that we've simply relied on CAPI bumping go toolchain versions in the past, and we want to continue to do that. If that's our intent - if we just want to follow CAPI versions - then I can document that instead...
There was a problem hiding this comment.
(Edited the above to fix incomplete thought!)
There was a problem hiding this comment.
I think this could quickly expand to a wider discussion on how many releases we support and what is our release cadence :) (which we might want to have at some point, maybe in a CAPG Community call)
I am happy either way
- with us bumping the
go toolchain xxdirective and keep that up to date with the latest supported patch release, as long as we don't touch thego xxdirective, as that's the minimum required version that can be used to build the project and I wouldn't want that to change - Follow what core CAPI does
My personal preference would be to follow core CAPI as closely as possible. They spent already a significant about of time oiling and perfecting the cadence and process and I think they are now at a point where folks are happy with it and it ties in well with the Go and the K8s processes. Also I think that's what the community expects anyway, and also that means we are always well compatible with that.
There was a problem hiding this comment.
In core CAPI we use trivy & govulncheck (via github action) to get notified on CVE's for the release branches and bump these (if required and viable) on CVE's to include the fixes in (potential) patch releases :-)
There was a problem hiding this comment.
We could think about doing that here too yeah.
I think we need to understand how that overlaps with dependabot.
Also we might be able to configure dependabot in a way so it bumps the go toolchain versions to higher patch versions when needed but without touching the main go directive.. 🤔 I know @cpanato is an expert on these things
There was a problem hiding this comment.
I'd also be in favor of following core CAPI. I think it makes the project easier to maintain long term as we implement a process that has been proved to work and don't have to focus on describing (and applying) our own.
It also means that future developers/maintainers that are new to CAPG but have experience in the CAPI ecosystem will have an easier time figuring out the intricacies of the project.
| @@ -63,6 +63,23 @@ Example versions: | |||
| - Patch release: `v0.1.1` | |||
| - Major release: `v1.0.0` | |||
|
|
|||
| The major and minor versions mirror the version of Cluster-API. Thus CAPG 1.11.x releases will use CAPI versions 1.11 | |||
|
|
|||
| The patch version is incremented for each release. Thus the first release of CAPG using CAPI 1.11 will 1.11.0, the second will be 1.11.1, etc | |||
There was a problem hiding this comment.
That has been true for now, but there might come a time where we need to release CAPG minor versions more frequently than CAPI minor releases.
This what many of the main CAPI providers out there already do. For example, to my knowledge, CAPA, CAPV, CAPZ don't have this CAPI to CAPI Provider minor version roping, and can and may release multiple provider versions in between core CAPI minor releases.
There was a problem hiding this comment.
I'll try to find some wording that makes it clear that we have this property today, but that we might not always have it in future. (It's a really human friendly property IMO, not having to constantly remember the translation factor!)
There was a problem hiding this comment.
I think we've been able to follow this until now because we haven't released that often, which meant we could just wait for a CAPI bump to create a new minor release. As we get more people involved with the project, I'd vote for increasing our release cadence. In this case, it will eventually force us to separate CAPG minor versions from CAPI's.
There was a problem hiding this comment.
We discussed this also in the office hours and we are leaning towards giving us more flexibility for the future and not commit to strict numbering going forward. cc. @cpanato too
There was a problem hiding this comment.
Note: I just want to share some knowledge, no hard opinions on what to do for CAPG :-)
Note: CAPV today also ~ follows CAPI release versions, but nowadays with an offset of 3 minors, and it always uses the .1 CAPI release to include compatibility to the next k8s release.
IMHO it makes sense to follow the CAPI release cadence, which helps for planning but of course its not set in stone and sometimes a project wants to have an additional minor due to reasons.
Following CAPI's release cadence might be challenging though and could require to test early for the next release.
At the end CAPI's release cadence (of x.x.1 relases) follows k8s release cadence.
| @@ -63,6 +63,23 @@ Example versions: | |||
| - Patch release: `v0.1.1` | |||
| - Major release: `v1.0.0` | |||
|
|
|||
| The major and minor versions mirror the version of Cluster-API. Thus CAPG 1.11.x releases will use CAPI versions 1.11 | |||
|
|
|||
| The patch version is incremented for each release. Thus the first release of CAPG using CAPI 1.11 will 1.11.0, the second will be 1.11.1, etc | |||
There was a problem hiding this comment.
I think we've been able to follow this until now because we haven't released that often, which meant we could just wait for a CAPI bump to create a new minor release. As we get more people involved with the project, I'd vote for increasing our release cadence. In this case, it will eventually force us to separate CAPG minor versions from CAPI's.
Documenting our branches and branch "philosophy"