diff --git a/changelog.d/19410.misc b/changelog.d/19410.misc new file mode 100644 index 0000000000..97a4070304 --- /dev/null +++ b/changelog.d/19410.misc @@ -0,0 +1 @@ +Add notes that new experimental features should have associated tracking issues. \ No newline at end of file diff --git a/docs/development/experimental_features.md b/docs/development/experimental_features.md index d6b11496cc..5a86017ecf 100644 --- a/docs/development/experimental_features.md +++ b/docs/development/experimental_features.md @@ -35,3 +35,30 @@ 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. +The configuration flag should link to the tracking issue for the experimental feature (see below). + + +## Tracking issues for experimental features + +In the interest of having some documentation around experimental features, without +polluting the stable documentation, all new experimental features should have a tracking issue with +[the `T-ExperimentalFeature` label](https://github.com/element-hq/synapse/issues?q=sort%3Aupdated-desc+state%3Aopen+label%3A%22T-ExperimentalFeature%22), +kept open as long as the experimental feature is present in Synapse. + +The configuration option for the feature should have a comment linking to the tracking issue, +for ease of discoverability. + +As a guideline, the issue should contain: + +- Context for why this experimental feature is in Synapse + - This could well be a link to somewhere else, where this context is already available. +- If applicable, why the feature is enabled by default. (Why do we need to enable it by default and why is it safe?) +- If applicable, setup instructions for any non-standard components or configuration needed by the feature. + (Ideally this will be moved to the configuration manual after stabilisation.) +- Design decisions behind the Synapse implementation. + (Ideally this will be moved to the developers' documentation after stabilisation.) +- Any caveats around the current implementation of the feature, such as: + - missing aspects + - breakage or incompatibility that is expected if/when the feature is stabilised, + or when the feature is turned on/off +- Criteria for how we know whether we can remove the feature in the future. diff --git a/synapse/config/experimental.py b/synapse/config/experimental.py index 0150b71621..1bd70ead09 100644 --- a/synapse/config/experimental.py +++ b/synapse/config/experimental.py @@ -366,7 +366,11 @@ class MSC3866Config: class ExperimentalConfig(Config): - """Config section for enabling experimental features""" + """Config section for enabling experimental features + + All new experimental features should have a tracking issue with the + `T-ExperimentalFeatures` label, kept open as long as the experimental + feature is present in Synapse.""" section = "experimental"