From 4b24b887c7004739ef0e7cc7e29c00d46fadc283 Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Tue, 1 Sep 2015 11:53:30 +0100
Subject: [PATCH] Document m.room.history_visibility

---
 specification/47_history_visibility.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 specification/47_history_visibility.rst

diff --git a/specification/47_history_visibility.rst b/specification/47_history_visibility.rst
new file mode 100644
index 00000000..d1c1f0d3
--- /dev/null
+++ b/specification/47_history_visibility.rst
@@ -0,0 +1,25 @@
+Room History Visibility
+=======================
+
+The visibility of events to users before they joined can be controlled by the
+``m.room.history_visibility`` state event.
+
+More specifically, the string value of the content key ``history_visibility``
+controls the visibility of events. The valid values are:
+
+- ``shared``
+- ``invited``
+- ``joined``
+
+By default, ``history_visibility`` is set to ``shared``.
+
+The rules governing whether a user is allowed to see an event depend solely on
+the state at that event:
+
+1. If the user was joined, allow.
+2. If the user was invited and the ``history_visibility`` was set to
+   ``invited`` or ``shared``, allow.
+3. If the user was neither invited nor joined but the ``history_visibility``
+   was set to ``shared``, allow.
+4. Otherwise, deny.
+