From e782619415d4bdae94f608d0dc590f2765441052 Mon Sep 17 00:00:00 2001 From: Sahdev Zala Date: Mon, 5 Sep 2022 20:59:00 -0400 Subject: [PATCH 1/3] Add features dev and support policy doc Related https://github.com/etcd-io/etcd/issues/13775 Signed-off-by: Sahdev Zala --- Documentation/contributor-guide/features.md | 39 +++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 Documentation/contributor-guide/features.md diff --git a/Documentation/contributor-guide/features.md b/Documentation/contributor-guide/features.md new file mode 100644 index 000000000..3481338f1 --- /dev/null +++ b/Documentation/contributor-guide/features.md @@ -0,0 +1,39 @@ +# Features + +This document provides general guidelines for adding and removing etcd features. The etcd features fall into two stages, experimental and stable. + +## Experimental + +Any new feature should be added as an experimental feature. An experimental feature is characterized as below: +- Associated with an issue with a clear need for such a feature. +- Any configuration flags related to the implementation of the feature are prefixed with `experimental` e.g. `--experimental-feature-name`. +- Any variable names related to the implementation of the feature are prefixed with `Experimental` e.g. `ExperimentalFeatureName`. +- Might be buggy. Enabling the feature may not work as expected. +- Support for such a feature may be dropped at any time without notice. +- Disabled by default when added initially. + +### Graduation to Stable + +It is important that experimental features don't get stuck in that stage. An experimental feature should move to the stable stage by following the lifecycle steps below: +- A new feature added in the latest release and disabled by default e.g. etcd v3.5 or v4.0 +- Given there are no open issues against the feature, it is ready for review to, + - Enable by default in the next release e.g. etcd v3.6 or v4.1 + - Move to the stable stage in the following release e.g. etcd v3.7 or v4.2. If release cycle takes longer, one year time frame can be used for the review. + +Patch releases should not be used for graduation. + +## Stable + +A stable feature is characterized as below: +- Supported as part of the supported releases of etcd. +- May be enabled by default. +- Discontinuation of support must follow the Feature Deprecation Process. + +### Feature Deprecation Process + +As the project evolves, a stable feature may sometimes need to be deprecated and removed. Such a situation should be handled using the steps below: +- Provide a deprecation message in the feature usage document before a planned release for feature deprecation. e.g. `To be deprecated in `. +- Deprecate the feature in the planned release with an appropriate message as part of the feature usage document. e.g. `Deprecated`. +- Deprecated feature then be removed in the following release. + +Overall, it can take two releases before a stable feature is completely removed. Patch releases should not be used for deprecation. From d38132e367b366ed3f11d2bf05b003455701c61d Mon Sep 17 00:00:00 2001 From: Sahdev Zala Date: Sat, 10 Sep 2022 16:46:00 -0400 Subject: [PATCH 2/3] Add features dev and support policy doc Addressed feedback with some added thoughts. Also, added Unsafe features. Related #13775 Signed-off-by: Sahdev Zala --- Documentation/contributor-guide/features.md | 51 +++++++++++++++------ 1 file changed, 36 insertions(+), 15 deletions(-) diff --git a/Documentation/contributor-guide/features.md b/Documentation/contributor-guide/features.md index 3481338f1..41168339d 100644 --- a/Documentation/contributor-guide/features.md +++ b/Documentation/contributor-guide/features.md @@ -1,26 +1,43 @@ # Features -This document provides general guidelines for adding and removing etcd features. The etcd features fall into two stages, experimental and stable. +This document provides an overview of etcd features and general guidelines for adding and removing features. The project maintainers can override the guidelines per the need of the project following the project governance. + +The etcd features fall into three stages, experimental, stable, and unsafe. ## Experimental Any new feature should be added as an experimental feature. An experimental feature is characterized as below: -- Associated with an issue with a clear need for such a feature. -- Any configuration flags related to the implementation of the feature are prefixed with `experimental` e.g. `--experimental-feature-name`. -- Any variable names related to the implementation of the feature are prefixed with `Experimental` e.g. `ExperimentalFeatureName`. -- Might be buggy. Enabling the feature may not work as expected. -- Support for such a feature may be dropped at any time without notice. -- Disabled by default when added initially. +- Might be buggy due to lack of user testing. Enabling the feature may not work as expected. +- Support for such a feature may be dropped at any time without notice +- Disabled by default when added initially + +### Minimum development requirements + +Experimental feature related development work is expected to be high quality, similar to any development work for the project. A related PR should meet the following criteria, +- Associated with an issue providing a clear need for such a feature +- Any configuration flags related to the implementation of the feature are prefixed with `experimental` e.g. `--experimental-feature-name` +- Any variable names related to the implementation of the feature are prefixed with `Experimental` e.g. `ExperimentalFeatureName` +- Provided with unit tests +- Provided with e2e test coverage for at least the basic scenario +- Added a CHANGELOG entry +- Disabled by default +- Approved by at least two project maintainers ### Graduation to Stable -It is important that experimental features don't get stuck in that stage. An experimental feature should move to the stable stage by following the lifecycle steps below: -- A new feature added in the latest release and disabled by default e.g. etcd v3.5 or v4.0 -- Given there are no open issues against the feature, it is ready for review to, - - Enable by default in the next release e.g. etcd v3.6 or v4.1 - - Move to the stable stage in the following release e.g. etcd v3.7 or v4.2. If release cycle takes longer, one year time frame can be used for the review. +It is important that experimental features don't get stuck in that stage. After a release of an intiial enablement (e.g. etcd v3.5), an experimental feature should be revisited in the following release (e.g. etcd v3.6 or after six months if release takes longer) and see if it's ready for graduation to the stable stage in the future release (e.g. etcd v3.7 or v4.0). If it's ready per discussions with the project maintainers, then depending on the scope of the feature, at least the following enhancements should be consiered to be worked on by opening a PR(s) and new issue(s) for tracking as needed, +- Fix any open issues against the feature +- Add robust e2e tests +- Enhance logs for proper debugging +- Update metrics and benchmarks if needed +- Upgrade/downgrade tests specially if there are changes in API, Raft, WAL protos. +- Enable by default if appropriate +- Modify the feature documentation and add a CHANGELOG entry to reflect that `--experimental` prefix in the feature name is expected to be dropped in the next release e.g. `Expected to be graduated and renamed to --feature-name in the future release` +- Create a new issue for future graduation with reference to the PR discussed here. Add the release label of the upcoming release for tracking. -Patch releases should not be used for graduation. +One release with above enhancements should give a good idea on the feature's stability. Unless there are open issues that can prevent feature gradution, the feature can move to the stable stage in the next release with a PR on feature rename, doc updates, and an entry in the CHANGELOG. All the related PRs and discussions should be approved by at least two project maintainers. + +Patch releases should not be considered for graduation. ## Stable @@ -33,7 +50,11 @@ A stable feature is characterized as below: As the project evolves, a stable feature may sometimes need to be deprecated and removed. Such a situation should be handled using the steps below: - Provide a deprecation message in the feature usage document before a planned release for feature deprecation. e.g. `To be deprecated in `. -- Deprecate the feature in the planned release with an appropriate message as part of the feature usage document. e.g. `Deprecated`. +- Deprecate the feature in the planned release with an appropriate message as part of the feature usage documentation. e.g. `Deprecated`. - Deprecated feature then be removed in the following release. -Overall, it can take two releases before a stable feature is completely removed. Patch releases should not be used for deprecation. +Overall, it can take two releases before a stable feature is completely removed. Patch releases should not be considered for deprecation. + +## Unsafe + +Unsafe features are rare and listed under the `Unsafe feature:` section in the etcd usage documentation. By default, they are disabled. They should be used with caution following documentation. Support for such features may be dropped at any time without notice. From 35801ddf02ea424dcd82252e0deb769bb45239b9 Mon Sep 17 00:00:00 2001 From: Sahdev Zala Date: Wed, 14 Sep 2022 17:12:23 -0400 Subject: [PATCH 3/3] Add an initial features doc Add an overview and initial development guidelines. Restructured the doc for a better readabiltiy and easier review, and per the previous review feedback. The TODOs will be addressed iteratively. Related #13775 Signed-off-by: Sahdev Zala --- Documentation/contributor-guide/features.md | 78 +++++++++------------ 1 file changed, 34 insertions(+), 44 deletions(-) diff --git a/Documentation/contributor-guide/features.md b/Documentation/contributor-guide/features.md index 41168339d..5ae83c1ea 100644 --- a/Documentation/contributor-guide/features.md +++ b/Documentation/contributor-guide/features.md @@ -1,60 +1,50 @@ # Features -This document provides an overview of etcd features and general guidelines for adding and removing features. The project maintainers can override the guidelines per the need of the project following the project governance. +This document provides an overview of etcd features and general development guidelines for adding and deprecating them. The project maintainers can override these guidelines per the need of the project following the project governance. + +## Overview The etcd features fall into three stages, experimental, stable, and unsafe. -## Experimental +### Experimental -Any new feature should be added as an experimental feature. An experimental feature is characterized as below: -- Might be buggy due to lack of user testing. Enabling the feature may not work as expected. +Any new feature is usually added as an experimental feature. An experimental feature is characterized as below: +- Might be buggy due to a lack of user testing. Enabling the feature may not work as expected. +- Disabled by default when added initially. - Support for such a feature may be dropped at any time without notice -- Disabled by default when added initially + - Feature related issues may be given lower priorities. + - It can be removed in the next minor or major release without following the feature deprecation policy unless it graduates to the stable future. -### Minimum development requirements +### Stable -Experimental feature related development work is expected to be high quality, similar to any development work for the project. A related PR should meet the following criteria, -- Associated with an issue providing a clear need for such a feature -- Any configuration flags related to the implementation of the feature are prefixed with `experimental` e.g. `--experimental-feature-name` -- Any variable names related to the implementation of the feature are prefixed with `Experimental` e.g. `ExperimentalFeatureName` -- Provided with unit tests -- Provided with e2e test coverage for at least the basic scenario -- Added a CHANGELOG entry -- Disabled by default -- Approved by at least two project maintainers - -### Graduation to Stable - -It is important that experimental features don't get stuck in that stage. After a release of an intiial enablement (e.g. etcd v3.5), an experimental feature should be revisited in the following release (e.g. etcd v3.6 or after six months if release takes longer) and see if it's ready for graduation to the stable stage in the future release (e.g. etcd v3.7 or v4.0). If it's ready per discussions with the project maintainers, then depending on the scope of the feature, at least the following enhancements should be consiered to be worked on by opening a PR(s) and new issue(s) for tracking as needed, -- Fix any open issues against the feature -- Add robust e2e tests -- Enhance logs for proper debugging -- Update metrics and benchmarks if needed -- Upgrade/downgrade tests specially if there are changes in API, Raft, WAL protos. -- Enable by default if appropriate -- Modify the feature documentation and add a CHANGELOG entry to reflect that `--experimental` prefix in the feature name is expected to be dropped in the next release e.g. `Expected to be graduated and renamed to --feature-name in the future release` -- Create a new issue for future graduation with reference to the PR discussed here. Add the release label of the upcoming release for tracking. - -One release with above enhancements should give a good idea on the feature's stability. Unless there are open issues that can prevent feature gradution, the feature can move to the stable stage in the next release with a PR on feature rename, doc updates, and an entry in the CHANGELOG. All the related PRs and discussions should be approved by at least two project maintainers. - -Patch releases should not be considered for graduation. - -## Stable - -A stable feature is characterized as below: +A stable feature is characterized as below: - Supported as part of the supported releases of etcd. - May be enabled by default. -- Discontinuation of support must follow the Feature Deprecation Process. +- Discontinuation of support must follow the feature deprecation policy. -### Feature Deprecation Process +### Unsafe -As the project evolves, a stable feature may sometimes need to be deprecated and removed. Such a situation should be handled using the steps below: -- Provide a deprecation message in the feature usage document before a planned release for feature deprecation. e.g. `To be deprecated in `. -- Deprecate the feature in the planned release with an appropriate message as part of the feature usage documentation. e.g. `Deprecated`. -- Deprecated feature then be removed in the following release. +Unsafe features are rare and listed under the `Unsafe feature:` section in the etcd usage documentation. By default, they are disabled. They should be used with caution following documentation. An unsafe feature can be removed in the next minor or major release without following feature deprecation policy. -Overall, it can take two releases before a stable feature is completely removed. Patch releases should not be considered for deprecation. +## Development Guidelines -## Unsafe +### Adding a new feature -Unsafe features are rare and listed under the `Unsafe feature:` section in the etcd usage documentation. By default, they are disabled. They should be used with caution following documentation. Support for such features may be dropped at any time without notice. +Any new enhancements to the etcd are typically added as an experimental feature. The general development requirements are listed below. They can be somewhat flexible depending on the scope of the feature and review discussions, and will evolve over time. +- Open an issue + - It must provide a clear need for the proposed feature. + - It should list development work items as checkboxes. There must be one work item towards future graduation to the stable future. + - Keep the issue open for tracking purpose until a decision is made on graduation. +- Open a Pull Request (PR) + - Provide unit tests. Integreation tests are also recommended as possible. + - Provide robust e2e test coverage. If the feature being added is complicated or quickly needed, maintainers can decide to go with e2e tests for basic coverage initially and have robust coverage added at the later time before feature graduation to the stable feature. + - Provide logs for proper debugging. + - Provide metrics and benchmarks as needed. + - The Feature should be disabled by default. + - Any configuration flags related to the implementation of the feature must be prefixed with `experimental` e.g. `--experimental-feature-name`. + - Add a CHANGELOG entry. +- At least two maintainers must approve feature requirements and related code changes. + +### Graduating an Experimental feature to Stable (TODO - spzala) + +### Deprecating a feature (TODO - spzala)