From 037d8c071cbe759f59e0b0ef7e43c106927f63c2 Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Thu, 7 Nov 2019 13:31:52 +0000 Subject: [PATCH] Document feature flag process This records the feature flag process we intend to use with Riot and also how that interacts with other teams and configuration. Fixes https://github.com/vector-im/riot-web/issues/11116 --- docs/config.md | 7 ++-- docs/feature-flags.md | 89 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+), 3 deletions(-) create mode 100644 docs/feature-flags.md diff --git a/docs/config.md b/docs/config.md index e609f26de3..d85deabb79 100644 --- a/docs/config.md +++ b/docs/config.md @@ -22,9 +22,10 @@ For a good example, see https://riot.im/develop/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 Riot 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. The available features are described in [labs.md](labs.md). +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 (usually) [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. `brand`: String to pass to your homeserver when configuring email notifications, to let the diff --git a/docs/feature-flags.md b/docs/feature-flags.md new file mode 100644 index 0000000000..a4dbbea7d2 --- /dev/null +++ b/docs/feature-flags.md @@ -0,0 +1,89 @@ +# Feature flags + +When developing new features for Riot, we use feature flags to give us more +flexibility and control over when and where those features are enabled. + +For example, flags make the following things possible: + +* Extended testing of a feature via labs on develop +* Enabling features when ready instead of the first moment the code is released +* Testing a feature with a specific set of users (by enabling only on a specific + Riot instance) + +The size of the feature controlled by a feature flag may vary widely: it could +be a large project like reactions or a smaller change to an existing algorithm. +A large project might use several feature flags if it's useful to control the +deployment of different portions independently. + +Everyone involved in a feature (engineering, design, product, reviewers) should +think about its deployment plan up front as best as possible so we can have the +right feature flags in place from the start. + +## Interaction with spec process + +Historically, we have often used feature flags to guard client features that +depend on unstable spec features. Unfortunately, there was never clear agreement +about how long such a flag should live for, when it should be removed, etc. + +Under the [new spec +process](https://github.com/matrix-org/matrix-doc/pull/2324), server-side +unstable features can be used by clients and enabled by default as long as +clients commit to doing the associated clean up work once a feature stabilises. + +## Starting work on a feature + +When starting work on a feature, we should create a matching feature flag: + +* Add a new + [setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.js) + of the form: +```js + "feature_cats": { + isFeature: true, + displayName: _td("Adds cats everywhere"), + supportedLevels: LEVELS_FEATURE, + default: false, + }, +``` +* Check whether the feature is enabled as appropriate: +```js + SettingsStore.isFeatureEnabled("feature_cats") +``` +* Add the feature to the [set of labs on develop](../riot.im/develop/config.json): +```json + "features": { + "feature_cats": "labs" + }, +``` +* Document the feature in the [labs documentation](labs.md) + +With these steps completed, the feature is disabled by default, but can be +enabled on develop by interested users for testing. + +Different features may have different deployment plans for when to enable where. The +following lists a few common options. + +## Enabling by default on develop + +Set the feature to `enable` in the [develop config](../riot.im/develop/config.json): + +```json + "features": { + "feature_cats": "enable" + }, +``` + +## Enabling by default on staging and app + +Set the feature to `enable` in the [app config](../riot.im/app/config.json). + +## Feature deployed successfully + +Once we're confident that a feature is working well, we should remove the flag: + +* Remove the [setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.js) +* Remove all `isFeatureEnabled` lines that test for the feature's setting +* Remove the feature from the [labs documentation](labs.md) +* Remove feature state from [develop](../riot.im/develop/config.json) and + [app](../riot.im/app/config.json) configs +* Celebrate! 🥳