matrix-org / matrix-org/matrix.org
Add a room upgrading 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
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