diff --git a/Documentation/contributor-guide/features.md b/Documentation/contributor-guide/features.md index 5ae83c1ea..a88ac9a25 100644 --- a/Documentation/contributor-guide/features.md +++ b/Documentation/contributor-guide/features.md @@ -34,6 +34,7 @@ Any new enhancements to the etcd are typically added as an experimental feature. - 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. + - Label the issue with `type/feature` and `experimental`. - 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. @@ -45,6 +46,38 @@ Any new enhancements to the etcd are typically added as an experimental feature. - Add a CHANGELOG entry. - At least two maintainers must approve feature requirements and related code changes. -### Graduating an Experimental feature to Stable (TODO - spzala) +### Graduating an Experimental feature to Stable -### Deprecating a feature (TODO - spzala) +It is important that experimental features don't get stuck in that stage. They should be revisited and moved to the stable stage following the graduation steps as described here. + +#### Locate graduation candidate +Decide if an experimental feature is ready for graduation to the stable stage. +- Find the issue that was used to enable the experimental feature initially. One way to find such issues is to search for issues with `type/feature` and `experimental` labels. +- Fix any known open issues against the feature. +- Make sure the feature was enabled for at least one previous release. Check the PR(s) reference from the issue to see when the feature related code changes were merged. + +#### Provide implementation +If an experimental feature is found ready for graduation to the stable stage, open a Pull Request (PR) with the following changes. +- Add robust e2e tests if not already provided. +- Add a new stable feature flag identical to the experimental feature flag but without the `--experimental` prefix. +- Deprecate the experimental feature following the [feature deprecation policy](#Deprecating-a-feature). +- Implementation must ensure that both the graduated and deprecated experimental feature flags work as expected. Note that both these flags will co-exist for the timeframe described in the feature deprecation policy. +- Enable the graduated feature by default if needed. + +At least two maintainers must approve the work. Patch releases should not be considered for graduation. + +### Deprecating a feature + +#### Experimental +An experimental feature deprecates when it graduates to the stable stage. +- Add a deprecation message in the documentation of the experimental feature with a recommendation to use related stable feature. e.g. `DEPRECATED. Use instead.` +- Add a `deprecated` label in the issue that was initially used to enable the experimental feature. + +#### Stable +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: +- Create an issue for tracking purpose. +- Add a deprecation message in the feature usage documentation before a planned release for feature deprecation. e.g. `To be deprecated in .`. If a new feature replaces the `To be deprecated` feature, then also provide a message saying so. e.g. `Use instead.`. +- Deprecate the feature in the planned release with a message as part of the feature usage documentation. e.g. `DEPRECATED`. If a new feature replaces the deprecated feature, then also provide a message saying so. e.g. `DEPRECATED. Use instead.`. +- Add a `deprecated` label in the related issue. + +Remove the deprecated feature in the following release. Close any related issue(s). At least two maintainers must approve the work. Patch releases should not be considered for deprecation.