Skip to content

Commit

Permalink
Add features dev and support policy doc
Browse files Browse the repository at this point in the history
Related etcd-io#13775

Signed-off-by: Sahdev Zala <spzala@us.ibm.com>
  • Loading branch information
spzala committed Sep 6, 2022
1 parent 73029fe commit 9b35481
Showing 1 changed file with 39 additions and 0 deletions.
39 changes: 39 additions & 0 deletions Documentation/contributor-guide/features.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# 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 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 enabled by default in the next release e.g. etcd v3.6 or v4.1
- It move to 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 to move to the stable stage.

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 <release>`.
- 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 should take two releases before a stable feature is completely removed. Patch releases should not be used for deprecation.

0 comments on commit 9b35481

Please sign in to comment.