|
|
@@ -0,0 +1,37 @@ |
|
|
|
# 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](../modules/index.md) 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. |