matrix-spec/specification/modules/room_upgrades.rst

.. Copyright 2019 New Vector Ltd
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
..
..     http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.

Room Upgrades
=============

.. _module:room-upgrades:

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

Events
------

{{m_room_tombstone_event}}

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.

{{room_upgrades_cs_http_api}}

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. 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.
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 may wish to automatically transfer/replicate
some of the user's personalized settings such as notifications, tags, etc.