vitalif
/
etcd
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add features dev and support policy doc 

Addressed feedback with some added thoughts. Also, added
Unsafe features.

Related #13775

Signed-off-by: Sahdev Zala <spzala@us.ibm.com>
dependabot/go_modules/go.uber.org/atomic-1.10.0
Sahdev Zala 2022-09-10 16:46:00 -04:00
parent e782619415
commit d38132e367
1 changed files with 36 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
Documentation/contributor-guide/features.md
View File

@ -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 <release>`.
- 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.