From 3e924941c3c6b3f29e7b889c4f6f6b9b3d181b51 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 17 Aug 2020 14:00:04 -0600 Subject: [PATCH] Update feature flags documentation for new feature behaviour --- docs/feature-flags.md | 68 +++++++++++++------------------------------ 1 file changed, 20 insertions(+), 48 deletions(-) diff --git a/docs/feature-flags.md b/docs/feature-flags.md index 115c3b25f2..5fb5545fdf 100644 --- a/docs/feature-flags.md +++ b/docs/feature-flags.md @@ -35,7 +35,7 @@ clients commit to doing the associated clean up work once a feature stabilises. When starting work on a feature, we should create a matching feature flag: 1. Add a new - [setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.js) + [setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.ts) of the form: ```js "feature_cats": { @@ -47,17 +47,9 @@ When starting work on a feature, we should create a matching feature flag: ``` 2. Check whether the feature is enabled as appropriate: ```js - SettingsStore.isFeatureEnabled("feature_cats") + SettingsStore.getValue("feature_cats") ``` -3. Add the feature to the set of labs on - [develop](https://github.com/vector-im/riot-web/blob/develop/riot.im/develop/config.json) - and [nightly](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/nightly/config.json): -```json - "features": { - "feature_cats": "labs" - }, -``` -4. Document the feature in the [labs documentation](https://github.com/vector-im/riot-web/blob/develop/docs/labs.md) +3. Document the feature in the [labs documentation](https://github.com/vector-im/riot-web/blob/develop/docs/labs.md) With these steps completed, the feature is disabled by default, but can be enabled on develop and nightly by interested users for testing. @@ -67,7 +59,7 @@ The following lists a few common options. ## Enabling by default on develop and nightly -Set the feature to `enable` in the +Set the feature to `true` in the [develop](https://github.com/vector-im/riot-web/blob/develop/riot.im/develop/config.json) and [nightly](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/nightly/config.json) @@ -75,34 +67,37 @@ configs: ```json "features": { - "feature_cats": "enable" + "feature_cats": true }, ``` ## Enabling by default on staging, app, and release -Set the feature to `enable` in the +Set the feature to `true` in the [staging / app](https://github.com/vector-im/riot-web/blob/develop/riot.im/app/config.json) and [release](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/release/config.json) configs. -**Warning:** While this does mean the feature is enabled by default for -https://app.element.io and official Element Desktop builds, it will not be enabled by -default for self-hosted installs, custom desktop builds, etc. To cover those -cases as well, the best options at the moment are converting to a regular -setting defaulted on or to remove the flag. Simply enabling the existing flag by -default in `Settings.js` -[does not work currently](https://github.com/vector-im/riot-web/issues/10360). +**Note:** The above will only enable the feature for https://app.element.io and official Element +Desktop builds. It will not be enabled for self-hosted installed, custom desktop builds, etc. To +cover these cases, change the setting's `default` in `Settings.ts` to `true`. ## Feature deployed successfully -Once we're confident that a feature is working well, we should remove the flag: +Once we're confident that a feature is working well, we should remove or convert the flag. -1. Remove the [setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.js) -2. Remove all `isFeatureEnabled` lines that test for the feature's setting +If the feature is meant to be turned off/on by the user: +1. Remove `isFeature` from the [setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.ts) +2. Change the `default` to `true` (if desired). 3. Remove the feature from the [labs documentation](https://github.com/vector-im/riot-web/blob/develop/docs/labs.md) -4. Remove feature state from +4. Celebrate! 🥳 + +If the feature is meant to be forced on (non-configurable): +1. Remove the [setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.ts) +2. Remove all `getValue` lines that test for the feature. +3. Remove the feature from the [labs documentation](https://github.com/vector-im/riot-web/blob/develop/docs/labs.md) +4. If applicable, remove the feature state from [develop](https://github.com/vector-im/riot-web/blob/develop/riot.im/develop/config.json), [nightly](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/nightly/config.json), [staging / app](https://github.com/vector-im/riot-web/blob/develop/riot.im/app/config.json), @@ -110,26 +105,3 @@ Once we're confident that a feature is working well, we should remove the flag: [release](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/release/config.json) configs 5. Celebrate! 🥳 - -## Convert to a regular setting (optional) - -Sometimes we decide a feature should always be user-controllable as a setting -even after it has been fully deployed. In that case, we would craft a new, -regular setting: - -1. Remove the feature flag from - [settings](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.js) - and add a regular setting with the appropriate levels for your feature -2. Replace the `isFeatureEnabled` lines with `getValue` or similar calls - according to the [settings - docs](https://github.com/matrix-org/matrix-react-sdk/blob/develop/docs/settings.md) - (checking carefully, as we may want a different mix of code paths when the - feature is always present but gated by a setting) -3. Remove the feature from the [labs documentation](https://github.com/vector-im/riot-web/blob/develop/docs/labs.md) -4. Remove feature state from - [develop](https://github.com/vector-im/riot-web/blob/develop/riot.im/develop/config.json), - [nightly](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/nightly/config.json), - [staging / app](https://github.com/vector-im/riot-web/blob/develop/riot.im/app/config.json), - and - [release](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/release/config.json) - configs