matrix-org / matrix-org/matrix.org

Add a room upgrading guide

Open
#2,704 23 comments 3 reactions 0 assignees View on GitHub
enhancement help wanted potential guide
Dominant language
JavaScript
Stars
616
Forks
463
Avg merge
2d 3h
Merged PRs (30d)
19

Description

The Matrix C2S API offers an [API endpoint for room upgrades](https://spec.matrix.org/latest/client-server-api/#server-behaviour-19). This endpoint makes some assumptions about the room's setup that in larger and federated communities has turned out to not necessarily cover all relevant bases. Neither do I know a client that warns users about potential issues or even calculates and displays those that it could definitely calculate.

Frequent issues include for example
- loss of parent space (technically, the former space(s) including the old room not exchanging it for the new one automatically)
- loss of aliases (the upgrading user being only member of one server, not all servers that provide an alias according to the [m.room.canonical_alias](https://spec.matrix.org/v1.14/client-server-api/#mroomcanonical_alias) event
- best practices for handling split rooms
- loss of (certain) room state
- rate limits for invites or proactive joins

This new guide should explain step by step how to handle all these potential issues properly to reduce the friction of room upgrades at this time. I expect this would essentially result in a script of how to plan and execute room upgrades manually. It might possible to also link further guides or tooling from the ecosystem as applicable.

Contributor guide

Open the contributing guide

Research direction

Start with the linked Matrix C2S room-upgrade endpoint and the m.room.canonical_alias event specification. Map the guide around the listed risks, including parent spaces, aliases, split rooms, room state, and invite or join rate limits. Done means a step-by-step manual plan for handling these cases, with relevant ecosystem guides or tools linked where applicable.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.