From 7793f07c814a44151ca8e8d6701380dce22d903e Mon Sep 17 00:00:00 2001
From: "J. Ryan Stinnett" <jryans@gmail.com>
Date: Thu, 15 Oct 2020 18:01:38 +0100
Subject: [PATCH] Document customisation points

https://github.com/matrix-org/matrix-react-sdk/pull/5327 adds a concept of
"customisation points" to keep custom functionality contained. This adds some
general guidance on how to use them.
---
 docs/customisations.md       | 34 ++++++++++++++++++++++++++++++++++
 src/customisations/README.md |  1 +
 2 files changed, 35 insertions(+)
 create mode 100644 docs/customisations.md
 create mode 120000 src/customisations/README.md

diff --git a/docs/customisations.md b/docs/customisations.md
new file mode 100644
index 0000000000..cea95af478
--- /dev/null
+++ b/docs/customisations.md
@@ -0,0 +1,34 @@
+# Customisations
+
+Element Web and the React SDK support "customisation points" that can be used to
+easily add custom logic specific to a particular deployment of Element Web.
+
+An example of this is the [security customisations
+module](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/customisations/Security.ts).
+This module in the React SDK only defines some empty functions and their types:
+it does not do anything by default.
+
+To make use of these customisation points, you will first need to fork Element
+Web so that you can add your own code. Even though the default module is part of
+the React SDK, you can still override it from the Element Web layer:
+
+1. Copy the default customisation module to
+   `element-web/src/customisations/YourNameSecurity.js`
+2. Edit customisations points and make sure export the ones you actually want to
+   activate
+3. Tweak the Element build process to use the customised module instead of the
+   default by adding this to end of the `plugins` array in `webpack.config.js`:
+
+```js
+new webpack.NormalModuleReplacementPlugin(
+    /src\/customisations\/Security.ts/,
+    path.resolve(__dirname, 'src/customisations/YourNameSecurity.ts'),
+),
+```
+
+If we add more customisation modules in the future, we'll likely improve these
+steps to remove the need for build changes like the above.
+
+By isolating customisations to their own module, this approach should remove the
+chance of merge conflicts when updating your fork, and thus simplify ongoing
+maintenance.
diff --git a/src/customisations/README.md b/src/customisations/README.md
new file mode 120000
index 0000000000..d2cbdd09d6
--- /dev/null
+++ b/src/customisations/README.md
@@ -0,0 +1 @@
+docs/customisations.md
\ No newline at end of file