Merge pull request #14986 from vector-im/travis/settings-v3

Settings v3: Update documentation and configs for new feature flag behaviour
pull/15013/head
Travis Ralston 2020-08-19 11:57:00 -06:00 committed by GitHub
commit 5f03004664
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 29 additions and 76 deletions

View File

@ -26,11 +26,7 @@
"defaultCountryCode": "GB", "defaultCountryCode": "GB",
"showLabsSettings": false, "showLabsSettings": false,
"features": { "features": {
"feature_new_spinner": "labs", "feature_new_spinner": false
"feature_pinning": "labs",
"feature_custom_status": "labs",
"feature_custom_tags": "labs",
"feature_state_counters": "labs"
}, },
"default_federate": true, "default_federate": true,
"default_theme": "light", "default_theme": "light",

View File

@ -22,12 +22,12 @@ For a good example, see https://develop.element.io/config.json.
`default_hs_url` is specified. When multiple sources are specified, it is unclear `default_hs_url` is specified. When multiple sources are specified, it is unclear
which should take priority and therefore the application cannot continue. which should take priority and therefore the application cannot continue.
* As of Element 1.4.0, identity servers are optional. See [Identity servers](#identity-servers) below. * As of Element 1.4.0, identity servers are optional. See [Identity servers](#identity-servers) below.
1. `features`: Lookup of optional features that may be `enable`d, `disable`d, or 1. `features`: Lookup of optional features that may be force-enabled (`true`) or force-disabled (`false`).
exposed to the user in the `labs` section of settings. The available When features are not listed here, their defaults will be used, and users can turn them on/off if `showLabsSettings`
optional experimental features vary from release to release and are [documented](labs.md). The feature flag process is allows them to. The available optional experimental features vary from release to release and are
[documented](feature-flags.md) as well. [documented](labs.md). The feature flag process is [documented](feature-flags.md) as well.
1. `showLabsSettings`: Shows the "labs" tab of user settings even when no `features` are enabled 1. `showLabsSettings`: Shows the "labs" tab of user settings. Useful to allow users to turn on experimental features
or present. Useful for getting at settings which may be otherwise hidden. they might not otherwise have access to.
1. `brand`: String to pass to your homeserver when configuring email notifications, to let the 1. `brand`: String to pass to your homeserver when configuring email notifications, to let the
homeserver know what email template to use when talking to you. homeserver know what email template to use when talking to you.
1. `branding`: Configures various branding and logo details, such as: 1. `branding`: Configures various branding and logo details, such as:

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

View File

@ -12,8 +12,7 @@
], ],
"hosting_signup_link": "https://element.io/matrix-services?utm_source=element-web&utm_medium=web", "hosting_signup_link": "https://element.io/matrix-services?utm_source=element-web&utm_medium=web",
"bug_report_endpoint_url": "https://element.io/bugreports/submit", "bug_report_endpoint_url": "https://element.io/bugreports/submit",
"features": { "showLabsSettings": false,
},
"piwik": { "piwik": {
"url": "https://piwik.riot.im/", "url": "https://piwik.riot.im/",
"siteId": 1, "siteId": 1,

View File

@ -12,21 +12,7 @@
], ],
"hosting_signup_link": "https://element.io/matrix-services?utm_source=element-web&utm_medium=web", "hosting_signup_link": "https://element.io/matrix-services?utm_source=element-web&utm_medium=web",
"bug_report_endpoint_url": "https://element.io/bugreports/submit", "bug_report_endpoint_url": "https://element.io/bugreports/submit",
"features": { "showLabsSettings": true,
"feature_new_spinner": "labs",
"feature_pinning": "labs",
"feature_custom_status": "labs",
"feature_custom_tags": "labs",
"feature_state_counters": "labs",
"feature_many_integration_managers": "labs",
"feature_mjolnir": "labs",
"feature_dm_verification": "labs",
"feature_bridge_state": "labs",
"feature_presence_in_room_list": "labs",
"feature_custom_themes": "labs",
"feature_roomlist_preview_reactions_dms": "labs",
"feature_roomlist_preview_reactions_all": "labs"
},
"piwik": { "piwik": {
"url": "https://piwik.riot.im/", "url": "https://piwik.riot.im/",
"siteId": 1, "siteId": 1,