From 6be7f511a4098998ef1622a043b4fd123f1ee46c Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 21 Sep 2021 10:46:19 -0400 Subject: [PATCH 1/4] Add documentation for experimental features. --- docs/SUMMARY.md | 1 + docs/development/experimental_features.md | 37 +++++++++++++++++++++++ 2 files changed, 38 insertions(+) create mode 100644 docs/development/experimental_features.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index fd0045e1ef96..bdb44543b83d 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -74,6 +74,7 @@ - [Testing]() - [OpenTracing](opentracing.md) - [Database Schemas](development/database_schema.md) + - [Experimental features](development/experimental_features.md) - [Synapse Architecture]() - [Log Contexts](log_contexts.md) - [Replication](replication.md) diff --git a/docs/development/experimental_features.md b/docs/development/experimental_features.md new file mode 100644 index 000000000000..febfed8a786b --- /dev/null +++ b/docs/development/experimental_features.md @@ -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). +* Developers are not confident are ready for use by general Synapse administrators/users + (e.g. a feature is incomplete, buggy, performs poorly, or needs further testing). + +Note that this does *not* include features which are not expected to be desirable +to a broad audience. The [module infrastructure](../modules/index.md) should 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 that experimental features require a configuration flag, +but if one should be included 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. From 86e0111b165cc16a54d106e00f7645ed7a3a8860 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 21 Sep 2021 10:47:19 -0400 Subject: [PATCH 2/4] Newsfragment --- changelog.d/10865.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/10865.doc diff --git a/changelog.d/10865.doc b/changelog.d/10865.doc new file mode 100644 index 000000000000..deeb0eedf363 --- /dev/null +++ b/changelog.d/10865.doc @@ -0,0 +1 @@ +Add developer documentation about experimental configuration flags. From 22693bf5d8eb782a3e93846c8ff4105c0d05e991 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 22 Sep 2021 07:05:58 -0400 Subject: [PATCH 3/4] Improve wording. Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- docs/development/experimental_features.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/development/experimental_features.md b/docs/development/experimental_features.md index febfed8a786b..c50b1627844b 100644 --- a/docs/development/experimental_features.md +++ b/docs/development/experimental_features.md @@ -4,11 +4,11 @@ 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). -* Developers are not confident are ready for use by general Synapse administrators/users +* 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 does *not* include features which are not expected to be desirable +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 be investigated for non-standard features. @@ -29,8 +29,8 @@ administrators to explicitly opt-in), although there are situations where it mak sense (from a product point-of-view) to enable features by default. This is expected and not an issue. -It is not a requirement that experimental features require a configuration flag, -but if one should be included if unsure. +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 From b305155f4b3ceaa882db0cd02730c4d7b98446ac Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 22 Sep 2021 07:33:05 -0400 Subject: [PATCH 4/4] Clarify wording. Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- docs/development/experimental_features.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/development/experimental_features.md b/docs/development/experimental_features.md index c50b1627844b..d6b11496cc4d 100644 --- a/docs/development/experimental_features.md +++ b/docs/development/experimental_features.md @@ -9,8 +9,8 @@ applicable for features which: (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 be -investigated for non-standard features. +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: