From 615e105a54ceec5710ac0afd423048f717a34103 Mon Sep 17 00:00:00 2001 From: clokep Date: Wed, 22 Sep 2021 13:42:09 +0000 Subject: [PATCH] deploy: 52913d56a5a2b07106774d97f4e188148d85a900 --- develop/404.html | 2 +- develop/CAPTCHA_SETUP.html | 2 +- develop/MSC1711_certificates_FAQ.html | 2 +- develop/admin_api/account_validity.html | 2 +- develop/admin_api/delete_group.html | 2 +- develop/admin_api/event_reports.html | 2 +- develop/admin_api/media_admin_api.html | 2 +- develop/admin_api/purge_history_api.html | 2 +- develop/admin_api/register_api.html | 2 +- develop/admin_api/room_membership.html | 2 +- develop/admin_api/rooms.html | 2 +- develop/admin_api/server_notices.html | 2 +- develop/admin_api/statistics.html | 2 +- develop/admin_api/user_admin_api.html | 2 +- develop/admin_api/version_api.html | 2 +- develop/application_services.html | 2 +- develop/auth_chain_difference_algorithm.html | 2 +- develop/code_style.html | 2 +- develop/consent_tracking.html | 2 +- develop/delegate.html | 2 +- develop/deprecation_policy.html | 2 +- develop/development/cas.html | 2 +- develop/development/contributing_guide.html | 2 +- develop/development/database_schema.html | 6 +- .../development/experimental_features.html | 288 ++++++++++++++++++ develop/development/git.html | 2 +- .../internal_documentation/index.html | 2 +- develop/development/room-dag-concepts.html | 2 +- develop/development/saml.html | 2 +- develop/development/url_previews.html | 2 +- develop/federate.html | 2 +- develop/index.html | 2 +- develop/jwt.html | 2 +- develop/log_contexts.html | 6 +- develop/manhole.html | 2 +- develop/media_repository.html | 2 +- develop/message_retention_policies.html | 2 +- develop/metrics-howto.html | 2 +- .../modules/account_validity_callbacks.html | 2 +- develop/modules/index.html | 2 +- develop/modules/porting_legacy_module.html | 2 +- .../modules/presence_router_callbacks.html | 2 +- develop/modules/spam_checker_callbacks.html | 2 +- .../modules/third_party_rules_callbacks.html | 2 +- develop/modules/writing_a_module.html | 2 +- develop/openid.html | 2 +- develop/opentracing.html | 2 +- develop/password_auth_providers.html | 2 +- develop/postgres.html | 2 +- develop/print.html | 35 ++- develop/replication.html | 2 +- develop/reverse_proxy.html | 2 +- develop/room_and_user_statistics.html | 2 +- develop/searchindex.js | 2 +- develop/searchindex.json | 2 +- develop/server_notices.html | 2 +- develop/setup/forward_proxy.html | 2 +- develop/setup/installation.html | 2 +- develop/sso_mapping_providers.html | 2 +- develop/structured_logging.html | 2 +- develop/synctl_workers.html | 2 +- develop/systemd-with-workers/index.html | 2 +- develop/tcp_replication.html | 2 +- develop/templates.html | 2 +- develop/turn-howto.html | 2 +- develop/upgrade.html | 2 +- .../usage/administration/admin_api/index.html | 2 +- .../admin_api/registration_tokens.html | 2 +- develop/usage/administration/index.html | 2 +- develop/usage/administration/request_log.html | 2 +- .../homeserver_sample_config.html | 2 +- develop/usage/configuration/index.html | 2 +- .../configuration/logging_sample_config.html | 2 +- .../user_authentication/index.html | 2 +- develop/user_directory.html | 2 +- develop/welcome_and_overview.html | 2 +- develop/workers.html | 2 +- 77 files changed, 401 insertions(+), 80 deletions(-) create mode 100644 develop/development/experimental_features.html diff --git a/develop/404.html b/develop/404.html index f6139a9b39..15eccdfea2 100644 --- a/develop/404.html +++ b/develop/404.html @@ -101,7 +101,7 @@ diff --git a/develop/CAPTCHA_SETUP.html b/develop/CAPTCHA_SETUP.html index bd7389f51d..c0e6ac0e95 100644 --- a/develop/CAPTCHA_SETUP.html +++ b/develop/CAPTCHA_SETUP.html @@ -99,7 +99,7 @@ diff --git a/develop/MSC1711_certificates_FAQ.html b/develop/MSC1711_certificates_FAQ.html index ffef692170..7538bb3f23 100644 --- a/develop/MSC1711_certificates_FAQ.html +++ b/develop/MSC1711_certificates_FAQ.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/account_validity.html b/develop/admin_api/account_validity.html index b9d59da0fd..58c9681656 100644 --- a/develop/admin_api/account_validity.html +++ b/develop/admin_api/account_validity.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/delete_group.html b/develop/admin_api/delete_group.html index 05728e5363..6f894ccd55 100644 --- a/develop/admin_api/delete_group.html +++ b/develop/admin_api/delete_group.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/event_reports.html b/develop/admin_api/event_reports.html index e6de889685..0cad36c62b 100644 --- a/develop/admin_api/event_reports.html +++ b/develop/admin_api/event_reports.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/media_admin_api.html b/develop/admin_api/media_admin_api.html index ae2edbfdf5..21a8dd3a9f 100644 --- a/develop/admin_api/media_admin_api.html +++ b/develop/admin_api/media_admin_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/purge_history_api.html b/develop/admin_api/purge_history_api.html index e30a049b85..69206b5095 100644 --- a/develop/admin_api/purge_history_api.html +++ b/develop/admin_api/purge_history_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/register_api.html b/develop/admin_api/register_api.html index 81f4e9aca4..f7d344f1c3 100644 --- a/develop/admin_api/register_api.html +++ b/develop/admin_api/register_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/room_membership.html b/develop/admin_api/room_membership.html index a7fbe1aa53..7406a148b7 100644 --- a/develop/admin_api/room_membership.html +++ b/develop/admin_api/room_membership.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/rooms.html b/develop/admin_api/rooms.html index d80698c79e..ba798260e6 100644 --- a/develop/admin_api/rooms.html +++ b/develop/admin_api/rooms.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/server_notices.html b/develop/admin_api/server_notices.html index 80a31a167b..40abf53bd3 100644 --- a/develop/admin_api/server_notices.html +++ b/develop/admin_api/server_notices.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/statistics.html b/develop/admin_api/statistics.html index 97a80bc442..2761c007d0 100644 --- a/develop/admin_api/statistics.html +++ b/develop/admin_api/statistics.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/user_admin_api.html b/develop/admin_api/user_admin_api.html index fc0b895c87..65b9cfe00e 100644 --- a/develop/admin_api/user_admin_api.html +++ b/develop/admin_api/user_admin_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/version_api.html b/develop/admin_api/version_api.html index 9654515f81..c31d017f76 100644 --- a/develop/admin_api/version_api.html +++ b/develop/admin_api/version_api.html @@ -99,7 +99,7 @@ diff --git a/develop/application_services.html b/develop/application_services.html index fd9c777026..a163e38009 100644 --- a/develop/application_services.html +++ b/develop/application_services.html @@ -99,7 +99,7 @@ diff --git a/develop/auth_chain_difference_algorithm.html b/develop/auth_chain_difference_algorithm.html index a82486bc57..d7205f7365 100644 --- a/develop/auth_chain_difference_algorithm.html +++ b/develop/auth_chain_difference_algorithm.html @@ -99,7 +99,7 @@ diff --git a/develop/code_style.html b/develop/code_style.html index 4eda21a683..9c5c59c06e 100644 --- a/develop/code_style.html +++ b/develop/code_style.html @@ -99,7 +99,7 @@ diff --git a/develop/consent_tracking.html b/develop/consent_tracking.html index 97f3aba3d9..d123c3ff16 100644 --- a/develop/consent_tracking.html +++ b/develop/consent_tracking.html @@ -99,7 +99,7 @@ diff --git a/develop/delegate.html b/develop/delegate.html index a270bd186c..797e61c36b 100644 --- a/develop/delegate.html +++ b/develop/delegate.html @@ -99,7 +99,7 @@ diff --git a/develop/deprecation_policy.html b/develop/deprecation_policy.html index 46265272cf..b30fd49e55 100644 --- a/develop/deprecation_policy.html +++ b/develop/deprecation_policy.html @@ -99,7 +99,7 @@ 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 @@ diff --git a/develop/federate.html b/develop/federate.html index 6636e236da..a42567f4c1 100644 --- a/develop/federate.html +++ b/develop/federate.html @@ -99,7 +99,7 @@ diff --git a/develop/index.html b/develop/index.html index 0408edba9b..7f12c01f1c 100644 --- a/develop/index.html +++ b/develop/index.html @@ -99,7 +99,7 @@ diff --git a/develop/jwt.html b/develop/jwt.html index 084b48d3ba..2d48285fd5 100644 --- a/develop/jwt.html +++ b/develop/jwt.html @@ -99,7 +99,7 @@ diff --git a/develop/log_contexts.html b/develop/log_contexts.html index 06e84de758..d06ecd3779 100644 --- a/develop/log_contexts.html +++ b/develop/log_contexts.html @@ -99,7 +99,7 @@ @@ -484,7 +484,7 @@ lead to leaked logcontexts which are incredibly hard to track down.