This documentation site is for the versions of Synapse maintained by the Matrix.org Foundation (github.com/matrix-org/synapse), available under the Apache 2.0 licence.
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.