matrix-spec/content/client-server-api/modules/room_upgrades.md

Room Upgrades

From time to time, a room may need to be upgraded to a different room version for a variety of reasons. This module defines a way for rooms to upgrade to a different room version when needed.

Events

{{% event event="m.room.tombstone" %}}

Client behaviour

Clients which understand m.room.tombstone events and the predecessor field on m.room.create events should communicate to the user that the room was upgraded. One way of accomplishing this would be hiding the old room from the user's room list and showing banners linking between the old and new room - ensuring that permalinks work when referencing the old room. Another approach may be to virtually merge the rooms such that the old room's timeline seamlessly continues into the new timeline without the user having to jump between the rooms.

{{% http-api spec="client-server" api="room_upgrades" %}}

Server behaviour

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. {{% changed-in v="1.4" %}} Creates a replacement room with a m.room.create event containing a predecessor field, the applicable room_version, and a type field which is copied from the predecessor room. If no type is set on the previous room, no type is specified on the new room's create event either.

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.

6. If possible, the power levels in the old room should also be modified to prevent sending 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 should automatically transfer/replicate some of the user's personalized settings such as notifications, tags, etc.