From a0abf58f87510f9adf5b5c52ea52b91243af0652 Mon Sep 17 00:00:00 2001 From: Sahdev Zala Date: Mon, 5 Sep 2022 20:59:00 -0400 Subject: [PATCH] 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 | 36 +++++++++++++++++++++ 1 file changed, 36 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 000000000000..9bcb87e3f0b9 --- /dev/null +++ b/Documentation/contributor-guide/features.md @@ -0,0 +1,36 @@ +# Features + +This document provides 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. + +### 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 using the criteria provided below: +- The feature was enabled for at least one major release or one year, whatever comes first. This time frame should be enough to find any potential bugs in the feature. +- There are no open issues against the feature. +- A PR is opened with needed changes in the configuration flag name, variables, help documentation, and anything related. + +## 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 Depreciation Process. + +### Feature Depreciation Process + +As the project evolves, sometimes a stable feature may need to be deprecated and removed. Such a situation should be handled using the steps below: +- Provide a depreciation message in the feature usage document before a planned major release for feature depreciation. e.g. `To be deprecated in `. +- Deprecate the feature in the planned major release with an appropriate message as part of the feature usage document. e.g. `Deprecated`. +- Deprecated feature then be removed in the following major release. + +Overall, it will take two major releases before a stable feature is completely removed.