From 49d1597d44d6cb05f2911846ccf7414131f26d22 Mon Sep 17 00:00:00 2001 From: Jason DeTiberus Date: Tue, 28 Apr 2020 16:18:01 -0400 Subject: [PATCH 1/4] Add additional context around experiment lifecycle --- CONTRIBUTING.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae1cbebf5dc2..d1ce237b9099 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,16 +77,31 @@ The Cluster API Enhacement Proposal is the process this project uses to adopt ne Proof of concepts, code experiments, or other initiatives can live under the `exp` folder and behind a feature gate. -- Experiments SHOULD ship with a CAEP marked as experimental. - Experiments SHOULD not modify any of the publicly exposed APIs (e.g. CRDs). - Experiments SHOULD not modify any existing CRD types outside of the experimental API group(s). - Experiments SHOULD not modify any existing command line contracts. - Experiments MUST not cause any breaking changes to existing (non-experimental) Go APIs. - Experiments SHOULD introduce utility helpers in the go APIs for experiments that cross multiple components and require support from bootstrap, control plane, or infrastructure providers. -- Experiments follow a strict lifecycle: Alpha -> Beta -> GA. - - Alpha-stage experiments SHOULD not be enabled by default. - - Inactive or outdated experiments will be deprecated and removed from the codebase, as outlined in Kubernetes deprecation policy +- Experiments follow a strict lifecycle: Early -> Late -> Promoted. + - Early-stage experiments: + - SHOULD not be enabled by default and any feature gates MUST be marked as 'Alpha' + - MUST be associated with a CAEP that is merged and in at least a provisional state + - MAY be considered inactive and eligible for removal if it does not graduate to Late-stage after 3 minor releases or 1 year, whichever is greater. + - Late-stage experiments: + - SHOULD be enabled by default, and any feature gates MUST be marked as 'Beta' + - MUST be associated with a CAEP that is at least in the experimental state + - MUST support conversions for any type changes + - MUST remain backwards compatible unless updates are coinciding with a breaking Cluster API release + - MAY be considered inactive and eligible for demotion back to Early-stage if it does not graduate to Promoted after 3 minor releases or 1 year, whichever is greater. + - Promoted experiments: + - MAY provide ways to be disabled and any feature gates MUST be marked as 'GA' + - MUST have undergone a full Kubernetes-style API review and have addressed any issues raised by the review + - MUST be associated with a CAEP that is in an implementable state and is fully up to date with the current implementation + - The associated CAEP MUST have a documented transition plan for moving into a non-experimental api group and code directory + - The associated CAEP MUST have documented upgrade steps for Existing Management and Workload Clusters + - The associated CAEP MUST have documented upgrade steps required to be implemented by out-of-tree bootstrap, control plane, and infrastructure providers. + - Promotion MUST coincide with a breaking Cluster API release ## Breaking Changes From 87ffed8b76d6dbdbf2089ac0c3cddece7cc0a364 Mon Sep 17 00:00:00 2001 From: Jason DeTiberus Date: Wed, 29 Apr 2020 12:48:03 -0400 Subject: [PATCH 2/4] address comments, fix headings --- CONTRIBUTING.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d1ce237b9099..42aa30eeaeb2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,13 +56,13 @@ release branch. For example, if the most recent branch is `release-0.2`, and the development for v0.3.0, a bug fix that merged to `master` that also affects `v0.2.x` may be considered for backporting to `release-0.2`. We generally do not accept PRs against older release branches. -### Features and bugs +## Features and bugs Open [issues](https://github.com/kubernetes-sigs/cluster-api/issues/new/choose) to report bugs, or minor features. For big feature, API and contract amendments, we follow the CAEP process as outlined below. -### Proposal process (CAEP) +## Proposal process (CAEP) The Cluster API Enhacement Proposal is the process this project uses to adopt new features, or changes to the APIs. @@ -73,7 +73,7 @@ The Cluster API Enhacement Proposal is the process this project uses to adopt ne - A proposal SHOULD be submitted first to the community using a collaborative writing platform, preferably Google Docs. - When using Google Docs, share the document with edit permissions for the [Kubernetes SIG Cluster Lifecycle mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-cluster-lifecycle). -### Experiments +## Experiments Proof of concepts, code experiments, or other initiatives can live under the `exp` folder and behind a feature gate. @@ -83,18 +83,19 @@ Proof of concepts, code experiments, or other initiatives can live under the `ex - Experiments MUST not cause any breaking changes to existing (non-experimental) Go APIs. - Experiments SHOULD introduce utility helpers in the go APIs for experiments that cross multiple components and require support from bootstrap, control plane, or infrastructure providers. -- Experiments follow a strict lifecycle: Early -> Late -> Promoted. - - Early-stage experiments: +- Experiments follow a strict lifecycle: Alpha -> Beta -> Graduation. + - Alpha-stage experiments: - SHOULD not be enabled by default and any feature gates MUST be marked as 'Alpha' - MUST be associated with a CAEP that is merged and in at least a provisional state - - MAY be considered inactive and eligible for removal if it does not graduate to Late-stage after 3 minor releases or 1 year, whichever is greater. - - Late-stage experiments: + - MAY be considered inactive and eligible for removal if it does not graduate to Late-stage after 2 minor releases. + - Beta-stage experiments: - SHOULD be enabled by default, and any feature gates MUST be marked as 'Beta' - MUST be associated with a CAEP that is at least in the experimental state - MUST support conversions for any type changes - MUST remain backwards compatible unless updates are coinciding with a breaking Cluster API release - - MAY be considered inactive and eligible for demotion back to Early-stage if it does not graduate to Promoted after 3 minor releases or 1 year, whichever is greater. - - Promoted experiments: + - MAY be considered inactive and marked as deprecated if it does not graduate to Promoted after 2 minor releases. + - Any deprecated Beta-stage experiment MAY be removed in the next minor release. +- Experiment Graduation checklist: - MAY provide ways to be disabled and any feature gates MUST be marked as 'GA' - MUST have undergone a full Kubernetes-style API review and have addressed any issues raised by the review - MUST be associated with a CAEP that is in an implementable state and is fully up to date with the current implementation @@ -128,20 +129,20 @@ There may, at times, need to be exceptions where breaking changes are allowed in discretion of the project's maintainers, and must be carefully considered before merging. An example of an allowed breaking change might be a fix for a behavioral bug that was released in an initial minor version (such as `v0.3.0`). -### Merge Approval +## Merge Approval Please see the [Kubernetes community document on pull requests](https://git.k8s.io/community/contributors/guide/pull-requests.md) for more information about the merge process. -### Google Doc Viewing Permissions +## Google Doc Viewing Permissions To gain viewing permissions to google docs in this project, please join either the [kubernetes-dev](https://groups.google.com/forum/#!forum/kubernetes-dev) or [kubernetes-sig-cluster-lifecycle](https://groups.google.com/forum/#!forum/kubernetes-sig-cluster-lifecycle) google group. -### Issue and Pull Request Management +## Issue and Pull Request Management Anyone may comment on issues and submit reviews for pull requests. However, in order to be assigned an issue or pull request, you must be a member of the [Kubernetes SIGs](https://github.com/kubernetes-sigs) GitHub organization. From e50ffef50bfd8908f4b793d8f22a305eca01d7d7 Mon Sep 17 00:00:00 2001 From: Jason DeTiberus Date: Wed, 29 Apr 2020 13:19:57 -0400 Subject: [PATCH 3/4] Refine experiment deprecation policy and graduation criteria --- CONTRIBUTING.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 42aa30eeaeb2..0f51960ce23d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,26 +83,33 @@ Proof of concepts, code experiments, or other initiatives can live under the `ex - Experiments MUST not cause any breaking changes to existing (non-experimental) Go APIs. - Experiments SHOULD introduce utility helpers in the go APIs for experiments that cross multiple components and require support from bootstrap, control plane, or infrastructure providers. -- Experiments follow a strict lifecycle: Alpha -> Beta -> Graduation. +- Experiments follow a strict lifecycle: Alpha -> Beta prior to Graduation. - Alpha-stage experiments: - SHOULD not be enabled by default and any feature gates MUST be marked as 'Alpha' - MUST be associated with a CAEP that is merged and in at least a provisional state - - MAY be considered inactive and eligible for removal if it does not graduate to Late-stage after 2 minor releases. + - MAY be considered inactive and marked as deprecated if the following does not happen within the course of 1 minor release cycle: + - Transition to Beta-stage + - Active development towards progressing to Beta-stage + - Either direct or downstream user evaluation + - Any deprecated Alpha-stage experiment MAY be removed in the next minor release. - Beta-stage experiments: - SHOULD be enabled by default, and any feature gates MUST be marked as 'Beta' - MUST be associated with a CAEP that is at least in the experimental state - MUST support conversions for any type changes - MUST remain backwards compatible unless updates are coinciding with a breaking Cluster API release - - MAY be considered inactive and marked as deprecated if it does not graduate to Promoted after 2 minor releases. - - Any deprecated Beta-stage experiment MAY be removed in the next minor release. + - MAY be considered inactive and marked as deprecated if the following does not happen within the course of 1 minor release cycle: + - Graduate + - Active development towards Graduation + - Either direct or downstream user consumption + - Any deprecated Beta-stage experiment MAY be removed after being deprecated for an entire minor release. +- Experiment Graduation MUST coincide with a breaking Cluster API release - Experiment Graduation checklist: - - MAY provide ways to be disabled and any feature gates MUST be marked as 'GA' - - MUST have undergone a full Kubernetes-style API review and have addressed any issues raised by the review - - MUST be associated with a CAEP that is in an implementable state and is fully up to date with the current implementation - - The associated CAEP MUST have a documented transition plan for moving into a non-experimental api group and code directory - - The associated CAEP MUST have documented upgrade steps for Existing Management and Workload Clusters - - The associated CAEP MUST have documented upgrade steps required to be implemented by out-of-tree bootstrap, control plane, and infrastructure providers. - - Promotion MUST coincide with a breaking Cluster API release + - [ ] If a graduating experiment plans to provide a way to be disabled, any feature gates MUST be marked as 'GA' + - [ ] Undergo a full Kubernetes-style API review and update the CAEP with the plan to address any issues raised + - [ ] CAEP MUST be in an implementable state and is fully up to date with the current implementation + - [ ] CAEP MUST define transition plan for moving out of the experimental api group and code directories + - [ ] CAEP MUST define any upgrade steps required for Existing Management and Workload Clusters + - [ ] CAEP MUST define any upgrade steps required to be implemented by out-of-tree bootstrap, control plane, and infrastructure providers. ## Breaking Changes From 0c36d10aa28383f48b5d2d8747cd7ecd045121ad Mon Sep 17 00:00:00 2001 From: Jason DeTiberus Date: Wed, 29 Apr 2020 13:20:22 -0400 Subject: [PATCH 4/4] Refine experiment deprecation policy and graduation criteria --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f51960ce23d..b90ea1fd944b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -104,8 +104,8 @@ Proof of concepts, code experiments, or other initiatives can live under the `ex - Any deprecated Beta-stage experiment MAY be removed after being deprecated for an entire minor release. - Experiment Graduation MUST coincide with a breaking Cluster API release - Experiment Graduation checklist: - - [ ] If a graduating experiment plans to provide a way to be disabled, any feature gates MUST be marked as 'GA' - - [ ] Undergo a full Kubernetes-style API review and update the CAEP with the plan to address any issues raised + - [ ] MAY provide a way to be disabled, any feature gates MUST be marked as 'GA' + - [ ] MUST undergo a full Kubernetes-style API review and update the CAEP with the plan to address any issues raised - [ ] CAEP MUST be in an implementable state and is fully up to date with the current implementation - [ ] CAEP MUST define transition plan for moving out of the experimental api group and code directories - [ ] CAEP MUST define any upgrade steps required for Existing Management and Workload Clusters