From 025fa06fc743bda7c4769b19991c40a1fb5d12ba Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Tue, 8 Dec 2020 14:03:08 +0000
Subject: [PATCH] Clarify config template comments (#8891)

---
 changelog.d/8891.doc          |  1 +
 docs/sample_config.yaml       | 12 ++++--------
 synapse/config/emailconfig.py |  5 ++---
 synapse/config/sso.py         |  7 ++-----
 4 files changed, 9 insertions(+), 16 deletions(-)
 create mode 100644 changelog.d/8891.doc

diff --git a/changelog.d/8891.doc b/changelog.d/8891.doc
new file mode 100644
index 000000000..c3947fe7c
--- /dev/null
+++ b/changelog.d/8891.doc
@@ -0,0 +1 @@
+Clarify comments around template directories in `sample_config.yaml`.
diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml
index 8712c580c..68c8f4f0e 100644
--- a/docs/sample_config.yaml
+++ b/docs/sample_config.yaml
@@ -1879,11 +1879,8 @@ sso:
     #  - https://my.custom.client/
 
     # Directory in which Synapse will try to find the template files below.
-    # If not set, default templates from within the Synapse package will be used.
-    #
-    # DO NOT UNCOMMENT THIS SETTING unless you want to customise the templates.
-    # If you *do* uncomment it, you will need to make sure that all the templates
-    # below are in the directory.
+    # If not set, or the files named below are not found within the template
+    # directory, default templates from within the Synapse package will be used.
     #
     # Synapse will look for the following templates in this directory:
     #
@@ -2113,9 +2110,8 @@ email:
   #validation_token_lifetime: 15m
 
   # Directory in which Synapse will try to find the template files below.
-  # If not set, default templates from within the Synapse package will be used.
-  #
-  # Do not uncomment this setting unless you want to customise the templates.
+  # If not set, or the files named below are not found within the template
+  # directory, default templates from within the Synapse package will be used.
   #
   # Synapse will look for the following templates in this directory:
   #
diff --git a/synapse/config/emailconfig.py b/synapse/config/emailconfig.py
index cceffbfee..7c8b64d84 100644
--- a/synapse/config/emailconfig.py
+++ b/synapse/config/emailconfig.py
@@ -390,9 +390,8 @@ class EmailConfig(Config):
           #validation_token_lifetime: 15m
 
           # Directory in which Synapse will try to find the template files below.
-          # If not set, default templates from within the Synapse package will be used.
-          #
-          # Do not uncomment this setting unless you want to customise the templates.
+          # If not set, or the files named below are not found within the template
+          # directory, default templates from within the Synapse package will be used.
           #
           # Synapse will look for the following templates in this directory:
           #
diff --git a/synapse/config/sso.py b/synapse/config/sso.py
index 442767616..93bbd4093 100644
--- a/synapse/config/sso.py
+++ b/synapse/config/sso.py
@@ -93,11 +93,8 @@ class SSOConfig(Config):
             #  - https://my.custom.client/
 
             # Directory in which Synapse will try to find the template files below.
-            # If not set, default templates from within the Synapse package will be used.
-            #
-            # DO NOT UNCOMMENT THIS SETTING unless you want to customise the templates.
-            # If you *do* uncomment it, you will need to make sure that all the templates
-            # below are in the directory.
+            # If not set, or the files named below are not found within the template
+            # directory, default templates from within the Synapse package will be used.
             #
             # Synapse will look for the following templates in this directory:
             #