From 6a071726a405b2b066d52cbf31129eaaa8671d23 Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Fri, 31 Jan 2025 08:29:21 +0000 Subject: [PATCH 1/6] feat(deprecation policy): added deprecation policy Signed-off-by: ivan katliarchuk --- docs/deprecation.md | 81 ++++++++++++++++++++++++++++++++ docs/proposal/design-template.md | 48 +++++++++++++++++++ 2 files changed, 129 insertions(+) create mode 100644 docs/deprecation.md create mode 100644 docs/proposal/design-template.md diff --git a/docs/deprecation.md b/docs/deprecation.md new file mode 100644 index 0000000000..9e442a485e --- /dev/null +++ b/docs/deprecation.md @@ -0,0 +1,81 @@ +# External DNS Deprecation Policy + +This document defines the Deprecation Policy for External Secrets Operator Components. + +Kubernetes is a dynamic system driven by APIs, which evolve with each new release. A crucial aspect of any API-driven system is having a well-defined deprecation policy. This policy informs users about APIs that are slated for removal or modification. Kubernetes follows this principle and periodically refines or upgrades its APIs or capabilities. Consequently, older features are marked as deprecated and eventually phased out. + +## Deprecation Policy + +We follow the [Kubernetes Deprecation Policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/) and [API Versioning Scheme](https://kubernetes.io/docs/reference/using-api/#api-versioning): alpha, beta, GA. It is therefore important to be aware of deprecation announcements and know when API versions will be removed, to help minimize the effect. + +### Scope + +* CRDs and API Objects and fields: `.Spec`, `.Status` and `.Status.Conditions[]` +* Annotations objects or it's values +* Controller Configuration: CLI flags & environment variables +* Metrics as defined in the [Kubernetes docs](https://kubernetes.io/docs/reference/using-api/deprecation-policy/#deprecating-a-metric) + +### Non-Scope + +Everything not listed in scope is not subject to this deprecation policy and it is subject to breaking changes, updates at any point in time, and deprecation - as long as it follows the Deprecation Process listed below. + +This includes, but isn't limited to: + +- Any feature/specific behavior not in Scope. +- Source code imports +- Source code refactorings +- Helm Charts +- Release process +- Docker Images (including multi-arch builds) +- Image Signature (including provenance, providers, keys) +- OLM-specific builds + +## Including features and behaviors to the Deprecation Policy + +Any `maintainer` or `contributor` may propose including a feature, component, or behavior out of scope to be in scope of the deprecation policy. + +The proposal must clearly outline the rationale for inclusion, the impact on users, stability, long term maintenance plan, and day-to-day activities, if such. + +The proposal must be formalized by submitting a `docs/proposal/xxx-design.md` document as a Pull Request. + +The proposal template is [here](docs/proposal/design-template.md) + +## Deprecation Process + +### Nomination of Deprecation + +Any maintainer may propose deprecating a feature, component, or behavior (both in and out of scope). In Scope changes must abide to the Deprecation Policy above. + +The proposal must clearly outline the rationale for deprecation, the impact on users, and any alternatives, if such. + +The proposal must be formalized by submiting a `design` document as a Pull Request. + +### Showcase to Maintainers + +The proposing maintainer must present the proposed deprecation to the maintainer group. This can be done synchronously during a community meeting or asynchronously, through a GitHub Pull Request. + +### Voting + +A majority vote of maintainers is required to approve the deprecation. +Votes may be conducted asynchronously, with a reasonable deadline for responses (e.g., one week). Lazy Consensus applies if the reasonable deadline is extended, with a minimal of at least one other maintainer approving the changes. + +### Implementation + +Upon approval, the proposing maintainer is responsible for implementing the changes required to mark the feature as deprecated. This includes: + +* Updating the codebase with deprecation warnings where applicable. + - log.Warn("The XXX is on the path of deprecation. We reccomend that you use YYY (link to docs)") +* Documenting the deprecation in release notes and relevant documentation. +* Updating APIs, metrics, or behaviors per the Kubernetes Deprecation Policy if in scope. +* If the feature is entirely deprecated archival of any associated repositories (external provider as example). + +### Deprecation Notice in Release + +Deprecation must be introduced in the next release. The release must follow semantic versioning: +* If the project is in the 0.x stage, a `minor` version `bump` is required. +* For projects 1.x and beyond, a major version bump is required. For the features completely removed. + - If it's a flag change/flip, the `minor` version `bump` is acceptable + +### Full Deprecation and Removal + +The removal must follow standard Kubernetes deprecation timelines if the feature is in scope. diff --git a/docs/proposal/design-template.md b/docs/proposal/design-template.md new file mode 100644 index 0000000000..4d75aaa98f --- /dev/null +++ b/docs/proposal/design-template.md @@ -0,0 +1,48 @@ + +```yaml +--- +title: New Feature or Deprecation/Removal Proposal +version: if applicable +authors: you, me +creation-date: 2025-01-01 +status: draft +--- +``` + +# New Feature or Deprecation/Removal Proposal + +## Table of Contents + + +// add it here + + +## Summary +Please provide a summary of this proposal. + +## Motivation +What is the motivation of this proposal? Why is it useful and relevant? + +### Goals +What are the goals of this proposal, what's the problem we want to solve? + +### Non-Goals +What are explicit non-goals of this proposal? + +## Proposal +How does the proposal look like? + +### User Stories +How would users use this feature, what are their needs? + +### API +Please describe the API (CRD or other) and show some examples. + +### Behavior +How should the new CRD or feature behave? Are there edge cases? + +### Drawbacks +If we implement this feature, what are drawbacks and disadvantages of this approach? + +## Alternatives +What alternatives do we have and what are their pros and cons? From 584f291e637510409309bb5f32addae0c819dcec Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Fri, 31 Jan 2025 08:48:36 +0000 Subject: [PATCH 2/6] feat(deprecation policy): added deprecation policy Signed-off-by: ivan katliarchuk --- docs/deprecation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/deprecation.md b/docs/deprecation.md index 9e442a485e..e9f0024c76 100644 --- a/docs/deprecation.md +++ b/docs/deprecation.md @@ -14,6 +14,7 @@ We follow the [Kubernetes Deprecation Policy](https://kubernetes.io/docs/referen * Annotations objects or it's values * Controller Configuration: CLI flags & environment variables * Metrics as defined in the [Kubernetes docs](https://kubernetes.io/docs/reference/using-api/deprecation-policy/#deprecating-a-metric) +* Revert a specific behavior without an alternative (flag,crd or annotation) ### Non-Scope From 507c1c5f075e913aae5dd8be1ebb80d4230d2278 Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Fri, 31 Jan 2025 08:50:03 +0000 Subject: [PATCH 3/6] feat(deprecation policy): added deprecation policy Signed-off-by: ivan katliarchuk --- docs/deprecation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/deprecation.md b/docs/deprecation.md index e9f0024c76..9be9db4f35 100644 --- a/docs/deprecation.md +++ b/docs/deprecation.md @@ -37,9 +37,9 @@ Any `maintainer` or `contributor` may propose including a feature, component, or The proposal must clearly outline the rationale for inclusion, the impact on users, stability, long term maintenance plan, and day-to-day activities, if such. -The proposal must be formalized by submitting a `docs/proposal/xxx-design.md` document as a Pull Request. +The proposal must be formalized by submitting a `docs/proposal/xxx-design.md` document as a Pull Request. Pull request must be labeled with `kind/proposal` -The proposal template is [here](docs/proposal/design-template.md) +The proposal template location is [here](docs/proposal/design-template.md) ## Deprecation Process From 9263e9415ed59684016584d1ce6a7542f185381a Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Fri, 31 Jan 2025 08:52:40 +0000 Subject: [PATCH 4/6] feat(deprecation policy): added deprecation policy Signed-off-by: ivan katliarchuk --- docs/deprecation.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/deprecation.md b/docs/deprecation.md index 9be9db4f35..49e30141f0 100644 --- a/docs/deprecation.md +++ b/docs/deprecation.md @@ -2,7 +2,9 @@ This document defines the Deprecation Policy for External Secrets Operator Components. -Kubernetes is a dynamic system driven by APIs, which evolve with each new release. A crucial aspect of any API-driven system is having a well-defined deprecation policy. This policy informs users about APIs that are slated for removal or modification. Kubernetes follows this principle and periodically refines or upgrades its APIs or capabilities. Consequently, older features are marked as deprecated and eventually phased out. +Kubernetes is a dynamic system driven by APIs, which evolve with each new release. A crucial aspect of any API-driven system is having a well-defined deprecation policy. This policy informs users about APIs that are slated for removal or modification. Kubernetes follows this principle and periodically refines or upgrades its APIs or capabilities. Consequently, older features are marked as deprecated and eventually phased out. To avoid breaking existing users, we should follow a simple deprecation policy for behaviors that a slated to be removed. + +The features and capabilities either to evolve or need to be removed. ## Deprecation Policy @@ -65,7 +67,7 @@ Votes may be conducted asynchronously, with a reasonable deadline for responses Upon approval, the proposing maintainer is responsible for implementing the changes required to mark the feature as deprecated. This includes: * Updating the codebase with deprecation warnings where applicable. - - log.Warn("The XXX is on the path of deprecation. We reccomend that you use YYY (link to docs)") + - log.Warn("The XXX is on the path of ***DEPRECATION***. We recommend that you use YYY (link to docs)") * Documenting the deprecation in release notes and relevant documentation. * Updating APIs, metrics, or behaviors per the Kubernetes Deprecation Policy if in scope. * If the feature is entirely deprecated archival of any associated repositories (external provider as example). From 53374b9fc42661d3469f3ddc024d1725124a7ebc Mon Sep 17 00:00:00 2001 From: Ivan Ka <5395690+ivankatliarchuk@users.noreply.github.com> Date: Fri, 31 Jan 2025 10:22:08 +0000 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com> --- docs/deprecation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/deprecation.md b/docs/deprecation.md index 49e30141f0..714ebf1fc8 100644 --- a/docs/deprecation.md +++ b/docs/deprecation.md @@ -1,6 +1,6 @@ # External DNS Deprecation Policy -This document defines the Deprecation Policy for External Secrets Operator Components. +This document defines the Deprecation Policy for External DNS. Kubernetes is a dynamic system driven by APIs, which evolve with each new release. A crucial aspect of any API-driven system is having a well-defined deprecation policy. This policy informs users about APIs that are slated for removal or modification. Kubernetes follows this principle and periodically refines or upgrades its APIs or capabilities. Consequently, older features are marked as deprecated and eventually phased out. To avoid breaking existing users, we should follow a simple deprecation policy for behaviors that a slated to be removed. @@ -31,7 +31,6 @@ This includes, but isn't limited to: - Release process - Docker Images (including multi-arch builds) - Image Signature (including provenance, providers, keys) -- OLM-specific builds ## Including features and behaviors to the Deprecation Policy @@ -39,9 +38,9 @@ Any `maintainer` or `contributor` may propose including a feature, component, or The proposal must clearly outline the rationale for inclusion, the impact on users, stability, long term maintenance plan, and day-to-day activities, if such. -The proposal must be formalized by submitting a `docs/proposal/xxx-design.md` document as a Pull Request. Pull request must be labeled with `kind/proposal` +The proposal must be formalized by submitting a `docs/proposal/EDP-XXX.md` document in a Pull Request. Pull request must be labeled with `kind/proposal`. -The proposal template location is [here](docs/proposal/design-template.md) +The proposal template location is [here](docs/proposal/design-template.md). The template is quite complete, one can remove any unnecessary or irrelevant section on a specific proposal. ## Deprecation Process @@ -70,11 +69,12 @@ Upon approval, the proposing maintainer is responsible for implementing the chan - log.Warn("The XXX is on the path of ***DEPRECATION***. We recommend that you use YYY (link to docs)") * Documenting the deprecation in release notes and relevant documentation. * Updating APIs, metrics, or behaviors per the Kubernetes Deprecation Policy if in scope. -* If the feature is entirely deprecated archival of any associated repositories (external provider as example). +* If the feature is entirely deprecated, archival of any associated repositories (external provider as example). ### Deprecation Notice in Release Deprecation must be introduced in the next release. The release must follow semantic versioning: + * If the project is in the 0.x stage, a `minor` version `bump` is required. * For projects 1.x and beyond, a major version bump is required. For the features completely removed. - If it's a flag change/flip, the `minor` version `bump` is acceptable From db45ddf19dcdbe9d4215a1ed6e0a506d7b96ceb4 Mon Sep 17 00:00:00 2001 From: ivan katliarchuk Date: Fri, 31 Jan 2025 10:24:07 +0000 Subject: [PATCH 6/6] feat(deprecation policy): added deprecation policy Signed-off-by: ivan katliarchuk --- mkdocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index e7bb2566c2..aa86f121ea 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -32,7 +32,8 @@ nav: - Rate Limits: docs/rate-limits.md - Contributing: - Kubernetes Contributions: CONTRIBUTING.md - - Release: docs/release.md + - Release: docs/release. + - Deprecation Policy: docs/deprecation.md - docs/contributing/* theme: