From e378de8379abcb85db8048b7dbd80b3851b4ac51 Mon Sep 17 00:00:00 2001
From: Kegan Dougal <kegan@matrix.org>
Date: Fri, 9 Oct 2015 11:04:11 +0100
Subject: [PATCH] Shuffle history visibility module to be in the module format

---
 specification/0-events.rst                   |  2 -
 specification/modules/history_visibility.rst | 44 +++++++++++++++-----
 2 files changed, 33 insertions(+), 13 deletions(-)

diff --git a/specification/0-events.rst b/specification/0-events.rst
index 16948462..e2373f96 100644
--- a/specification/0-events.rst
+++ b/specification/0-events.rst
@@ -26,8 +26,6 @@ prefixed with ``m.``
 
 {{m_room_create_event}}
 
-{{m_room_history_visibility_event}}
-
 {{m_room_join_rules_event}}
 
 {{m_room_member_event}}
diff --git a/specification/modules/history_visibility.rst b/specification/modules/history_visibility.rst
index 371282bd..4f0c8976 100644
--- a/specification/modules/history_visibility.rst
+++ b/specification/modules/history_visibility.rst
@@ -1,21 +1,36 @@
 Room History Visibility
------------------------
+=======================
 
 .. _module:history-visibility:
 
-Whether a member of a room can see the events that happened in a room from
-before they joined the room is controlled by the ``history_visibility`` key
-of the ``m.room.history_visibility`` state event. The valid values for
-``history_visibility`` are:
+This module adds support for controlling the visibility of previous events in a
+room. Whether a member of a room can see the events that happened in a room from
+before they joined the room is controlled by the ``m.room.history_visibility``
+event outlined below. Visibility can take the form of one of three options:
+
+- ``shared`` - Previous events are always shown to newly joined members.
+- ``invited`` - Previous events are shown to newly joined members from the point
+  they were invited onwards.
+- ``joined`` - Previous events are shown to newly joined members from the point
+  they joined the room onwards.
+
+Events
+------
+
+{{m_room_history_visibility_event}}
 
-- ``shared``
-- ``invited``
-- ``joined``
+Client behaviour
+----------------
 
-By default if no ``history_visibility`` is set it is assumed to be ``shared``.
+Clients that implement this module MUST present to the user the possible options
+for setting history visibility when creating a room. 
 
-The rules governing whether a user is allowed to see an event depend solely on
-the state of the room at that event:
+Server behaviour
+----------------
+
+By default if no ``history_visibility`` is set the visibility is assumed to be
+``shared``. The rules governing whether a user is allowed to see an event depend
+solely on the state of the room *at that event*:
 
 1. If the user was joined, allow.
 2. If the user was invited and the ``history_visibility`` was set to
@@ -24,3 +39,10 @@ the state of the room at that event:
    was set to ``shared``, allow.
 4. Otherwise, deny.
 
+Security considerations
+-----------------------
+
+The default value for ``history_visibility`` is ``shared`` for
+backwards-compatibility reasons. Clients need to be aware that by not setting
+this event they are exposing all of their room history to anyone in the room.
+