diff options
| author | Patrick Cloke <clokep@users.noreply.github.com> | 2021-09-22 09:41:42 -0400 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-09-22 13:41:42 +0000 |
| commit | 52913d56a5a2b07106774d97f4e188148d85a900 (patch) | |
| tree | 3c931895417a21c7649fe4ad54fb4431d788ab14 | |
| parent | Opt out of cache expiry for `get_users_who_share_room_with_user` (#10826) (diff) | |
| download | synapse-52913d56a5a2b07106774d97f4e188148d85a900.tar.xz | |
Add documentation for experimental feature flags. (#10865)
| -rw-r--r-- | changelog.d/10865.doc | 1 | ||||
| -rw-r--r-- | docs/SUMMARY.md | 1 | ||||
| -rw-r--r-- | docs/development/experimental_features.md | 37 |
3 files changed, 39 insertions, 0 deletions
diff --git a/changelog.d/10865.doc b/changelog.d/10865.doc new file mode 100644 index 0000000000..deeb0eedf3 --- /dev/null +++ b/changelog.d/10865.doc @@ -0,0 +1 @@ +Add developer documentation about experimental configuration flags. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index fd0045e1ef..bdb44543b8 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 0000000000..d6b11496cc --- /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 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. |