Merge pull request #2817 from aaronraimist/room-v1

Improve wording of room version 1 warnings

specification/rooms/v1.rst

@@ -80,18 +80,23 @@ may be used by other room versions, and as such servers should be aware of which
 version room they are dealing with prior to executing a given algorithm.
 
 .. WARNING::
-   Although room version 1 is the most popular room version, it is known to have
+   Although there are many rooms using room version 1, it is known to have
    undesirable effects. Servers implementing support for room version 1 should be
    aware that restrictions should be generally relaxed and that inconsistencies
-   may occur until room version 2 (or later) is ready and adopted.
+   may occur.
 
 State resolution
 ~~~~~~~~~~~~~~~~
 
 .. WARNING::
-  This section documents the state resolution algorithm as implemented by
+   Room version 1 is known to have bugs that can cause the state of rooms to reset
-  Synapse as of December 2017 (and therefore the de-facto Matrix protocol).
+   to older versions of the room's state. For example this could mean that users
-  However, this algorithm is known to have some problems.
+   who had joined the room may be removed from the room, admins and moderators
+   could lose their power level, and users who have been banned from the room may
+   be able to rejoin. Other state events such as the the room's name or topic could
+   also reset to a previous version.
+
+   This is fixed in the state resolution algorithm introduced in room version 2.
 
 The room state :math:`S'(E)` after an event :math:`E` is defined in terms of
 the room state :math:`S(E)` before :math:`E`, and depends on whether