Skip to content

Commit

Permalink
Sync version and release docs with main
Browse files Browse the repository at this point in the history 
Signed-off-by: Stefan Büringer buringerst@vmware.com
  • Loading branch information
@sbueringer
sbueringer committed Jan 22, 2024
1 parent a150f71 commit 28c59e6
Show file tree
Hide file tree
Showing 3 changed files with 31 additions and 46 deletions.
29 changes: 3 additions & 26 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
- [Proposal process (CAEP)](#proposal-process-caep)
- [Triaging E2E test failures](#triaging-e2e-test-failures)
- [Reviewing a Patch](#reviewing-a-patch)
- [Reviews](#reviews)
- [Reviews](#reviews)
- [Approvals](#approvals)
- [Features and bugs](#features-and-bugs)
- [Experiments](#experiments)
Expand Down Expand Up @@ -250,30 +250,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)

Expand Down Expand Up @@ -313,7 +290,7 @@ In case you want to run E2E test locally, please refer to the [Testing](https://

## Reviewing a Patch

## Reviews
### Reviews

> Parts of the following content have been adapted from https://google.github.io/eng-practices/review.
Expand Down
24 changes: 14 additions & 10 deletions docs/book/src/reference/versions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -83,9 +85,9 @@ These diagrams show the relationships between components in a Cluster API releas
| Kubernetes v1.24 | ✓ | ✓ | ✓ | ✓ (only workload) |
| Kubernetes v1.25 | ✓ | ✓ | ✓ | ✓ |
| Kubernetes v1.26 | ✓ | ✓ | ✓ | ✓ |
| Kubernetes v1.27 | | ✓ | ✓ | ✓ |
| Kubernetes v1.28 | | | ✓ | ✓ |

| 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.
Previous Kubernetes **minor** versions are not affected.
Expand All @@ -107,8 +109,9 @@ The Core Provider also talks to API server of every Workload Cluster. Therefore,
| Kubernetes v1.24 + kubeadm/v1beta3 | ✓ | ✓ | ✓ | ✓ (only workload) |
| Kubernetes v1.25 + kubeadm/v1beta3 | ✓ | ✓ | ✓ | ✓ |
| Kubernetes v1.26 + kubeadm/v1beta3 | ✓ | ✓ | ✓ | ✓ |
| Kubernetes v1.27 + kubeadm/v1beta3 | | ✓ | ✓ | ✓ |
| Kubernetes v1.28 + 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.

Expand All @@ -125,8 +128,9 @@ The Kubeadm Bootstrap Provider generates kubeadm configuration using the API ver
| Kubernetes v1.24 + etcd/v3 | ✓ | ✓ | ✓ | ✓ (only workload) |
| Kubernetes v1.25 + etcd/v3 | ✓ | ✓ | ✓ | ✓ |
| Kubernetes v1.26 + etcd/v3 | ✓ | ✓ | ✓ | ✓ |
| Kubernetes v1.27 + etcd/v3 | | ✓ | ✓ | ✓ |
| Kubernetes v1.28 + 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.

Expand Down
24 changes: 14 additions & 10 deletions docs/release/release-cycle.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down

0 comments on commit 28c59e6

Please sign in to comment.