From ef13aef8c3751166032907ab2041fb1386fd7077 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 10 Feb 2019 19:31:25 -0700 Subject: [PATCH] Clarify the recommendations for "transferable state" Fixes https://github.com/matrix-org/matrix-doc/issues/1843 --- api/client-server/room_upgrades.yaml | 4 +--- specification/modules/room_upgrades.rst | 22 +++++++++++++++++----- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/api/client-server/room_upgrades.yaml b/api/client-server/room_upgrades.yaml index 6511d9fc..55ee14dc 100644 --- a/api/client-server/room_upgrades.yaml +++ b/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: [] diff --git a/specification/modules/room_upgrades.rst b/specification/modules/room_upgrades.rst index 49ff4414..20efbabd 100644 --- a/specification/modules/room_upgrades.rst +++ b/specification/modules/room_upgrades.rst @@ -47,9 +47,21 @@ 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`` + + Membership events should not be transferred to the new room. + 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 +69,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.