Add notes that new experimental features should have associated tracking issues. (#19410)

Signed-off-by: Olivier 'reivilibre <oliverw@matrix.org>

changelog.d/19410.misc

@@ -0,0 +1 @@
+Add notes that new experimental features should have associated tracking issues.

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.

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"