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

Settings v3: Update documentation and configs for new feature flag behaviour
2024-10-01 01:26:12 -04:00 · 2020-08-19 11:57:00 -06:00 · 2020-08-19 11:57:00 -06:00 · 5f03004664
commit 5f03004664
parent 7435175a76 2c952b422b
5 changed files with 29 additions and 76 deletions
--- a/config.sample.json
+++ b/config.sample.json
@ -26,11 +26,7 @@
    "defaultCountryCode": "GB",
    "showLabsSettings": false,
    "features": {
-        "feature_new_spinner": "labs",
-        "feature_pinning": "labs",
-        "feature_custom_status": "labs",
-        "feature_custom_tags": "labs",
-        "feature_state_counters": "labs"
+        "feature_new_spinner": false
    },
    "default_federate": true,
    "default_theme": "light",
--- a/docs/config.md
+++ b/docs/config.md
@ -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
     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.
-1. `features`: Lookup of optional features that may be `enable`d, `disable`d, or
-   exposed to the user in the `labs` section of settings. The available
-   optional experimental features vary from release to release and are [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
-   or present. Useful for getting at settings which may be otherwise hidden.
+1. `features`: Lookup of optional features that may be force-enabled (`true`) or force-disabled (`false`).
+   When features are not listed here, their defaults will be used, and users can turn them on/off if `showLabsSettings`
+   allows them to. The available optional experimental features vary from release to release and are 
+   [documented](labs.md). The feature flag process is [documented](feature-flags.md) as well.
+1. `showLabsSettings`: Shows the "labs" tab of user settings. Useful to allow users to turn on experimental features
+   they might not otherwise have access to.
 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.
 1. `branding`: Configures various branding and logo details, such as:
--- 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
--- a/element.io/app/config.json
+++ b/element.io/app/config.json
@ -12,8 +12,7 @@
    ],
    "hosting_signup_link": "https://element.io/matrix-services?utm_source=element-web&utm_medium=web",
    "bug_report_endpoint_url": "https://element.io/bugreports/submit",
-    "features": {
-    },
+    "showLabsSettings": false,
    "piwik": {
        "url": "https://piwik.riot.im/",
        "siteId": 1,
--- a/element.io/develop/config.json
+++ b/element.io/develop/config.json
@ -12,21 +12,7 @@
    ],
    "hosting_signup_link": "https://element.io/matrix-services?utm_source=element-web&utm_medium=web",
    "bug_report_endpoint_url": "https://element.io/bugreports/submit",
-    "features": {
-        "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"
-    },
+    "showLabsSettings": true,
    "piwik": {
        "url": "https://piwik.riot.im/",
        "siteId": 1,