PrivateCoffee/element-web
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3

Update feature flags documentation for new feature behaviour

Browse source
This commit is contained in:
Travis Ralston 2020-08-17 14:00:04 -06:00
parent 2a25c6aaa4
commit 3e924941c3
1 changed files with 20 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

68
docs/feature-flags.md
View file

@ -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: When starting work on a feature, we should create a matching feature flag:
1. Add a new 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: of the form:
```js ```js
"feature_cats": { "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: 2. Check whether the feature is enabled as appropriate:
```js ```js
SettingsStore.isFeatureEnabled("feature_cats") SettingsStore.getValue("feature_cats")
``` ```
3. Add the feature to the set of labs on 3. Document the feature in the [labs documentation](https://github.com/vector-im/riot-web/blob/develop/docs/labs.md)
[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)
With these steps completed, the feature is disabled by default, but can be With these steps completed, the feature is disabled by default, but can be
enabled on develop and nightly by interested users for testing. 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 ## 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) [develop](https://github.com/vector-im/riot-web/blob/develop/riot.im/develop/config.json)
and and
[nightly](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/nightly/config.json) [nightly](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/nightly/config.json)
@ -75,34 +67,37 @@ configs:
```json ```json
"features": { "features": {
"feature_cats": "enable" "feature_cats": true
}, },
``` ```
## Enabling by default on staging, app, and release ## 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) [staging / app](https://github.com/vector-im/riot-web/blob/develop/riot.im/app/config.json)
and and
[release](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/release/config.json) [release](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/release/config.json)
configs. configs.
**Warning:** While this does mean the feature is enabled by default for **Note:** The above will only enable the feature for https://app.element.io and official Element
https://app.element.io and official Element Desktop builds, it will not be enabled by Desktop builds. It will not be enabled for self-hosted installed, custom desktop builds, etc. To
default for self-hosted installs, custom desktop builds, etc. To cover those cover these cases, change the setting's `default` in `Settings.ts` to `true`.
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).
## Feature deployed successfully ## 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) If the feature is meant to be turned off/on by the user:
2. Remove all `isFeatureEnabled` lines that test for the feature's setting 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) 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), [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), [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), [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) [release](https://github.com/vector-im/riot-desktop/blob/develop/riot.im/release/config.json)
configs configs
5. Celebrate! 🥳 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