Merge pull request #1875 from matrix-org/travis/clarify-upgrades

Clarify the recommendations for "transferable state"

api/client-server/room_upgrades.yaml

@@ -31,9 +31,7 @@ paths:
     post:
       summary: Upgrades a room to a new room version.
       description: |-
-        Upgrades the given room to a particular room version, migrating as much
-        data as possible over to the new room. See the `room_upgrades <#room-upgrades>`_
-        module for more information on what this entails.
+        Upgrades the given room to a particular room version.
       operationId: upgradeRoom
       security:
         - accessToken: []

changelogs/client_server/newsfragments/1791.feature

@@ -1 +1 @@
-Add room version upgrades
+Add room version upgrades.

changelogs/client_server/newsfragments/1817.deprecation

@@ -1 +1 @@
-Remove references to presence lists
+Remove references to presence lists.

changelogs/client_server/newsfragments/1875.feature

@@ -0,0 +1 @@
+Add room version upgrades.

specification/modules/room_upgrades.rst

@@ -47,9 +47,26 @@ When the client requests to upgrade a known room to a known version, the server:
 1. Checks that the user has permission to send ``m.room.tombstone`` events in the room.
 2. Creates a replacement room with a ``m.room.create`` event containing a ``predecessor``
    field and the applicable ``room_version``.
-3. Replicates the power levels, privacy, topic, and other transferable state events to
-   the new room. This generally excludes membership events but may include client-specified
-   events and other presentation details.
+3. Replicates transferable state events to the new room. The exact details for what is
+   transferred is left as an implementation detail, however the recommended state events
+   to transfer are:
+
+   * ``m.room.server_acl``
+   * ``m.room.encryption``
+   * ``m.room.name``
+   * ``m.room.avatar``
+   * ``m.room.topic``
+   * ``m.room.guest_access``
+   * ``m.room.history_visibility``
+   * ``m.room.join_rules``
+   * ``m.room.power_levels``
+
+   Membership events should not be transferred to the new room due to technical limitations
+   of servers not being able to impersonate people from other homeservers. Additionally,
+   servers should not transfer state events which are sensitive to who sent them, such as
+   events outside of the Matrix namespace where clients may rely on the sender to match
+   certain criteria.
+
 4. Moves any local aliases to the new room.
 5. Sends a ``m.room.tombstone`` event to the old room to indicate that it is not intended
    to be used any further.
@@ -57,5 +74,5 @@ When the client requests to upgrade a known room to a known version, the server:
    of events and inviting new users. For example, setting ``events_default`` and ``invite``
    to the greater of ``50`` and ``users_default + 1``.
 
-When a user joins the new room, the server may wish to automatically transfer/replicate
-some of the user's personalized settings such as notifications, tags, etc.
+When a user joins the new room, the server should automatically transfer/replicate some of
+the user's personalized settings such as notifications, tags, etc.