diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2553bdb63650..4b25e5352c81 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -251,30 +251,7 @@ When submitting the PR remember to label it with the 📖 (:book:) icon. ## Releases -- Minor versions CAN be planned and scheduled for each quarter, or sooner if necessary. - - Each minor version is preceded with one or more planning session. - - Planning consists of one or more backlog grooming meetings, roadmap amendments, - and CAEP proposal reviews. - - Cluster API uses [GitHub milestones](https://github.com/kubernetes-sigs/cluster-api/milestones) to track work - for minor releases. - - Adding an issue to a milestone provides forward visibility on what the next release will be, so, as soon as there - is the intent to work on an issue for a specific target release, contributors are expected to work with maintainers to - set the milestone on the issue so it will be tracked for the release (note: only major features/bug fixes specifically - targeting a release must be tracked; everything else will simply merge when ready without additional toil). - - Before adding an issue to a release milestone, maintainers must ensure that the issue have been triaged and - there is an assignee who expressed the intent to complete the work before the release date. - - An issue being in the milestone doesn't guarantee inclusion in the release; this depends on the work being - completed before the release code freeze target date. - - Code freeze is in effect at least 72 hours (3 days) before a major/minor release. - - Maintainers should communicate the code freeze date at a community meeting preceding the code freeze date. - - Only critical bug fixes may be merged in between freeze & release. - - Each bug MUST be associated with an open issue and properly triaged. - - PRs MUST be approved by at least 2 project maintainers. - - First approver should `/approve` and `/hold`. - - Second approver should `/approve` and `/hold cancel`. - - [E2E Test grid](https://testgrid.k8s.io/sig-cluster-lifecycle-cluster-api#capi%20e2e%20tests) SHOULD be green before cutting a release. -- Patch versions CAN be planned and scheduled each month for supported minor releases. -- Dates in a release are approximations and always subject to change. +Cluster API release process is described in [this document](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/release/release-cycle.md). ## Proposal process (CAEP) diff --git a/docs/book/src/reference/versions.md b/docs/book/src/reference/versions.md index 126af63dbd46..c282be2e465d 100644 --- a/docs/book/src/reference/versions.md +++ b/docs/book/src/reference/versions.md @@ -20,9 +20,8 @@ A Cluster API minor release supports (when it's initially created): * 6 Kubernetes minor releases for the workload cluster (N - N-5) When a new Kubernetes minor release is available, we will try to support it in an upcoming Cluster API patch release -(although only in the latest supported Cluster API minor release). But this depends on the changes made in Kubernetes, if -the corresponding required changes in Cluster API are too invasive we won't backport the support and users have to wait -for the next Cluster API minor release. +(although only in the latest supported Cluster API minor release). See Cluster API [release cycle](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/release/release-cycle.md) +and [release calendars](https://github.com/kubernetes-sigs/cluster-api/tree/main/docs/release/releases) for more details. For example, Cluster API v1.5.0 would support the following Kubernetes versions: * v1.24.x to v1.27.x for the management cluster @@ -34,6 +33,9 @@ Support in this context means that we: * have test coverage * accept bug fixes +Important! if the changes in Cluster API required to support a new Kubernetes release are too invasive, we won't backport +it to older releases and users have to wait for the next Cluster API minor release. + Important! This is not a replacement/alternative for upstream Kubernetes support policies! Support for versions of Kubernetes which itself are out of support is limited to "Cluster API can start a Cluster with this Kubernetes version" and "Cluster API can upgrade to the next Kubernetes version"; it does not include any extended support to Kubernetes itself. @@ -80,9 +82,9 @@ These diagrams show the relationships between components in a Cluster API releas | Kubernetes v1.24 | ✓ | ✓ | ✓ (only workload) | ✓ (only workload) | | Kubernetes v1.25 | ✓ | ✓ | ✓ | ✓ (only workload) | | Kubernetes v1.26 | ✓ | ✓ | ✓ | ✓ | -| Kubernetes v1.27 | ✓ | ✓ | ✓ | ✓ | -| Kubernetes v1.28 | | ✓ | ✓ | ✓ | -| Kubernetes v1.29 | | | ✓ | ✓ | +| Kubernetes v1.27 | ✓ >= v1.4.2 | ✓ | ✓ | ✓ | +| Kubernetes v1.28 | | ✓ >= v1.5.1 | ✓ | ✓ | +| Kubernetes v1.29 | | | ✓ >= v1.6.1 | ✓ | \* There is an issue with CRDs in Kubernetes v1.23.{0-2}. ClusterClass with patches is affected by that (for more details please see [this issue](https://github.com/kubernetes-sigs/cluster-api/issues/5990)). Therefore we recommend to use Kubernetes v1.23.3+ with ClusterClass. @@ -100,9 +102,9 @@ The Core Provider also talks to API server of every Workload Cluster. Therefore, | Kubernetes v1.24 + kubeadm/v1beta3 | ✓ | ✓ | ✓ (only workload) | ✓ (only workload) | | Kubernetes v1.25 + kubeadm/v1beta3 | ✓ | ✓ | ✓ | ✓ (only workload) | | Kubernetes v1.26 + kubeadm/v1beta3 | ✓ | ✓ | ✓ | ✓ | -| Kubernetes v1.27 + kubeadm/v1beta3 | ✓ | ✓ | ✓ | ✓ | -| Kubernetes v1.28 + kubeadm/v1beta3 | | ✓ | ✓ | ✓ | -| Kubernetes v1.29 + kubeadm/v1beta3 | | | ✓ | ✓ | +| Kubernetes v1.27 + kubeadm/v1beta3 | ✓ >= v1.4.2 | ✓ | ✓ | ✓ | +| Kubernetes v1.28 + kubeadm/v1beta3 | | ✓ >= v1.5.1 | ✓ | ✓ | +| Kubernetes v1.29 + kubeadm/v1beta3 | | | ✓ >= v1.6.1 | ✓ | The Kubeadm Bootstrap Provider generates kubeadm configuration using the API version recommended for the target Kubernetes version. @@ -116,9 +118,9 @@ The Kubeadm Bootstrap Provider generates kubeadm configuration using the API ver | Kubernetes v1.24 + etcd/v3 | ✓ | ✓ | ✓ (only workload) | ✓ (only workload) | | Kubernetes v1.25 + etcd/v3 | ✓ | ✓ | ✓ | ✓ (only workload) | | Kubernetes v1.26 + etcd/v3 | ✓ | ✓ | ✓ | ✓ | -| Kubernetes v1.27 + etcd/v3 | ✓ | ✓ | ✓ | ✓ | -| Kubernetes v1.28 + etcd/v3 | | ✓ | ✓ | ✓ | -| Kubernetes v1.29 + etcd/v3 | | | ✓ | ✓ | +| Kubernetes v1.27 + etcd/v3 | ✓ >= v1.4.2 | ✓ | ✓ | ✓ | +| Kubernetes v1.28 + etcd/v3 | | ✓ >= v1.5.1 | ✓ | ✓ | +| Kubernetes v1.29 + etcd/v3 | | | ✓ >= v1.6.1 | ✓ | The Kubeadm Control Plane Provider talks to the API server and etcd members of every Workload Cluster whose control plane it owns. It uses the etcd v3 API. diff --git a/docs/release/release-cycle.md b/docs/release/release-cycle.md index 0abe4db80ba4..35328ddd040f 100644 --- a/docs/release/release-cycle.md +++ b/docs/release/release-cycle.md @@ -2,10 +2,7 @@ The release cycle is the time between when we start working on a release on the `main` branch until the `.0` release (e.g. `v1.3.0`) is released. -**Note**: For the `v1.3` and `v1.4` releases we assume each release cycle will last approximately 4 months (~ 17 weeks). -The release cycle will follow a 4 month cadence for 2023. The release cycle duration will be revisited in 2024. - -A release cycle can be split up into the following phases: +Each release cycle will last approximately 4 months (~ 17 weeks) and it can be split up into the following phases: * Week 1-12: Active development * All changes impacting providers' adoption of Cluster API should be implemented and merged in this period. Exceptions @@ -32,16 +29,23 @@ A release cycle can be split up into the following phases: * `x.y.0` GA release is created based on the release branch * After that: * **Note** The following is the responsibility of the release team of the following release cycle. - * `x.y.1+`: Monthly patch releases will be released based on the release branch - * Cherry-picks to the release branch are allowed according to the [backport policy](https://github.com/kubernetes-sigs/cluster-api/blob/main/CONTRIBUTING.md#backporting-a-patch) - * Providers create releases using the new CAPI minor release when they are ready - * Development of the next release can now officially start on the main branch + * `x.y.1+` monthly patch release: Monthly patch releases will be released based on the release branch + * `x.y.1+` extra patch release: In order to quickly provide official support for a new Kubernetes minor release to Cluster API users, + an additional patch release will be released approximately one week after a new Kubernetes minor release is available. + * The additional patch release will be created only for the latest supported Cluster API minor release. + * The additional patch release might be canceled if: + * The release date for the additional patch release overlaps the release date of a monthly patch release (+/- 5 business days). + * Cluster API maintainers determine that required changes in Cluster API to support the new release are too + invasive and cannot be back ported. + * Cherry-picks to the release branch are allowed according to the [backport policy](https://github.com/kubernetes-sigs/cluster-api/blob/main/CONTRIBUTING.md#backporting-a-patch) + * Providers create releases using the new CAPI minor release when they are ready + * Development of the next release can now officially start on the main branch Some additional notes: * Support for new Kubernetes minor versions (for management and workload clusters) is first implemented - on the main branch, then cherry-picked into supported release branches when feasible and eventually - released in the next monthly patch release(s). + on the main branch, then cherry-picked into the release branch for the latest minor version only, and then + released according to the `x.y.1+` extra patch release schedule defined above. * **Note**: We usually don't have to bump Go dependencies to support new Kubernetes minor versions as it's not necessary to run on a management cluster with the new version or create a workload cluster with the new version. If it becomes necessary to bump dependencies to a new CR/Kubernetes minor version, the change cannot be cherry-picked