synapse/docs/development/experimental_features.md

Implementing experimental features in Synapse

It can be desirable to implement "experimental" features which are disabled by default and must be explicitly enabled via the Synapse configuration. This is applicable for features which:

• Are unstable in the Matrix spec (e.g. those defined by an MSC that has not yet been merged).
• Developers are not confident in their use by general Synapse administrators/users (e.g. a feature is incomplete, buggy, performs poorly, or needs further testing).

Note that this only really applies to features which are expected to be desirable to a broad audience. The module infrastructure should instead be investigated for non-standard features.

Guarding experimental features behind configuration flags should help with some of the following scenarios:

• Ensure that clients do not assume that unstable features exist (failing gracefully if they do not).
• Unstable features do not become de-facto standards and can be removed aggressively (since only those who have opted-in will be affected).
• Ease finding the implementation of unstable features in Synapse (for future removal or stabilization).
• Ease testing a feature (or removal of feature) due to enabling/disabling without code changes. It also becomes possible to ask for wider testing, if desired.

Experimental configuration flags should be disabled by default (requiring Synapse administrators to explicitly opt-in), although there are situations where it makes sense (from a product point-of-view) to enable features by default. This is expected and not an issue.

It is not a requirement for experimental features to be behind a configuration flag, but one should be used if unsure.

New experimental configuration flags should be added under the experimental configuration key (see the synapse.config.experimental file) and either explain (briefly) what is being enabled, or include the MSC number.