From 615e105a54ceec5710ac0afd423048f717a34103 Mon Sep 17 00:00:00 2001 From: clokep Date: Wed, 22 Sep 2021 13:42:09 +0000 Subject: deploy: 52913d56a5a2b07106774d97f4e188148d85a900 --- develop/development/cas.html | 2 +- develop/development/contributing_guide.html | 2 +- develop/development/database_schema.html | 6 +- develop/development/experimental_features.html | 288 +++++++++++++++++++++ develop/development/git.html | 2 +- .../development/internal_documentation/index.html | 2 +- develop/development/room-dag-concepts.html | 2 +- develop/development/saml.html | 2 +- develop/development/url_previews.html | 2 +- 9 files changed, 298 insertions(+), 10 deletions(-) create mode 100644 develop/development/experimental_features.html (limited to 'develop/development') diff --git a/develop/development/cas.html b/develop/development/cas.html index 940580dc80..821b5c72be 100644 --- a/develop/development/cas.html +++ b/develop/development/cas.html @@ -99,7 +99,7 @@ diff --git a/develop/development/contributing_guide.html b/develop/development/contributing_guide.html index 894a84b171..7c0613b12a 100644 --- a/develop/development/contributing_guide.html +++ b/develop/development/contributing_guide.html @@ -99,7 +99,7 @@ diff --git a/develop/development/database_schema.html b/develop/development/database_schema.html index 9e58553b90..46a5e15c02 100644 --- a/develop/development/database_schema.html +++ b/develop/development/database_schema.html @@ -99,7 +99,7 @@ @@ -315,7 +315,7 @@ in Python, evaluates to True.

- + @@ -333,7 +333,7 @@ in Python, evaluates to True.

- + diff --git a/develop/development/experimental_features.html b/develop/development/experimental_features.html new file mode 100644 index 0000000000..732ca04f10 --- /dev/null +++ b/develop/development/experimental_features.html @@ -0,0 +1,288 @@ + + + + + + Experimental features - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +

+ + +

+

+ + + + + + +

+ + + +

+ + + + + + + + + + + + + + + + +

+

+ + + + + + + + +

+

+ +

+ +

+ +

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.

+ +

+ + +

+

+ + + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/develop/development/git.html b/develop/development/git.html index f2438420e5..1a1c35f37b 100644 --- a/develop/development/git.html +++ b/develop/development/git.html @@ -99,7 +99,7 @@ diff --git a/develop/development/internal_documentation/index.html b/develop/development/internal_documentation/index.html index bbd12e4cc4..e328539fbf 100644 --- a/develop/development/internal_documentation/index.html +++ b/develop/development/internal_documentation/index.html @@ -99,7 +99,7 @@ diff --git a/develop/development/room-dag-concepts.html b/develop/development/room-dag-concepts.html index c389127ac6..4c0cd0a2fd 100644 --- a/develop/development/room-dag-concepts.html +++ b/develop/development/room-dag-concepts.html @@ -99,7 +99,7 @@ diff --git a/develop/development/saml.html b/develop/development/saml.html index 49686449c4..5202959a94 100644 --- a/develop/development/saml.html +++ b/develop/development/saml.html @@ -99,7 +99,7 @@ diff --git a/develop/development/url_previews.html b/develop/development/url_previews.html index 3d10262a81..5ae569794c 100644 --- a/develop/development/url_previews.html +++ b/develop/development/url_previews.html @@ -99,7 +99,7 @@ -- cgit 1.5.1