Add room upgrading guide #2861

HarHarLinks · 2025-08-06T17:11:43Z

🎩 Website & Content WG in collaboration with T&S R&D WG

Signed-off-by: HarHarLinks 2803622+HarHarLinks@users.noreply.github.com

Tackles #2704, though there may be multiple iterations in this or in followup-PRs - depends on the Hydra release timeline and contributor availabilities so the exact approach remains to be seen.

The plan is to also(?) release a blog post or incorporate this somehow into a blog post shortly before the Hydra release.

The prioritization/planned iterations are:

iteration
- what & why
- how incl recommendations
- client support
- room v12 miniversion: just linking to the info that has been published. mention again that perhaps a service account show create these rooms
- tools & scripts link dump
- References and further reading
iteration
- room v12 proper summary and recommendations
iteration
- add limitations, add references from the recommendations
- How to upgrade a room (advanced)
- split rooms

✔️ Checklist

Check for common mistakes:
- Wrap plain URLs in <> to linkify them (learn more).
- Use the right level of headings: The page title will use a level 1 headings, so your headings should use level 2 and below.
- Use internal links: when linking to another page on https://matrix.org, use the Zola [label](@/target.md) syntax.
For blog posts:
- Verify the date and post ordering on the /blog page, especially for multiple posts on the same day. Prefer UTC format, e.g. 2025-12-01T14:00:00Z for Dec 1st, 2025, 2pm UTC.
- Set the correct author and category. Browse existing ones at https://matrix.org/author/ and https://matrix.org/category/ to match them.
Let us know if you are contributing in a specific role, such as on behalf of an organisation or team, for example.
Let us know if your PR is time-sensitive in any way.
Mention any issues related to the PR. Use GitHub keywords as appropriate.
Your individual commits or pull request is signed off.

Co-Authored-By: Cat <catalanlover@protonmail.com> Co-Authored-By: Gnuxie <Gnuxie@protonmail.com> Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

HarHarLinks · 2025-08-06T17:19:19Z

We would welcome any help to turn this current draft into a proper text. If you have time and would like to contribute by turning bullet points into text, please submit suggestions by reviewing this PR!

We think we have covered the essential points, but of course additions are also welcome!

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

cloudflare-workers-and-pages · 2025-08-06T17:28:19Z

Deploying matrix-website with Cloudflare Pages

Latest commit:	`f4becf0`
Status:	✅ Deploy successful!
Preview URL:	https://4c2ea5fd.matrix-website.pages.dev
Branch Preview URL:	https://harharlinks-room-upgrading-g.matrix-website.pages.dev

View logs

jimmackenzie · 2025-08-06T18:18:19Z

Pleased to see progress on this! Please tag me for a review ahead of publication, I'll pop it to the top of my list.

content/docs/communities/administration/_index.md

Co-authored-by: Tobias Fella <9750016+TobiasFella@users.noreply.github.com>

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

content/docs/communities/administration/_index.md

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

HarHarLinks · 2025-08-10T18:52:47Z

Pleased to see progress on this! Please tag me for a review ahead of publication, I'll pop it to the top of my list.

@jimmackenzie please take a look!

content/docs/communities/administration/_index.md

cyb3rko · 2025-08-11T02:04:54Z

We've planned to release it soon.
What do you think, how far is the draft away from being ready to be published?

HarHarLinks · 2025-08-11T08:32:32Z

We've planned to release it soon. What do you think, how far is the draft away from being ready to be published?

Good from my side, please review. Also need a review from the foundation.

Idea to copy the same thing to the blog is still up in the air.

Need info from @jimmackenzie to align about what is planed from foundation side.

thibaultamartin

Approving because imperfect doc is better than no docs, but there are a few nits

content/docs/communities/administration/_index.md

davidmehren · 2025-08-10T22:26:53Z

content/docs/communities/administration/_index.md

+
+**Advanced upgrading:**  
+There are some reasons why your client might not be showing you the upgrading UI despite an upgrade being available, including:
+- Your homeserver implementation or admin doesn't recommend it, via the [homeserver's configuration](https://spec.matrix.org/latest/client-server-api/#mroom_versions-capability).


I'm confused that this talks about homeserver config and links to the spec that doesn't.

content/docs/communities/administration/_index.md

jimmackenzie · 2025-08-11T08:55:32Z

We've planned to release it soon. What do you think, how far is the draft away from being ready to be published?

Good from my side, please review. Also need a review from the foundation.

Idea to copy the same thing to the blog is still up in the air.

Need info from @jimmackenzie to align about what is planed from foundation side.

Starting my review now.

jimmackenzie

Approved, with a number of suggestions (removing passive voice, simplifying some sentences and formatting suggestions). Also incorporated some suggestions from the other reviewers.

content/docs/communities/administration/_index.md

Co-authored-by: David Mehren <git@herrmehren.de> Co-authored-by: Thibault Martin <thibaultamartin@users.noreply.github.com>

Co-authored-by: Jim Mackenzie <jimm@element.io>

KitsuneRal

Adding Quaternion to the lists.

content/docs/communities/administration/_index.md

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

Co-authored-by: Alexey Rusakov <Kitsune-Ral@users.sf.net>

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> Co-authored-by: Jim Mackenzie <jimm@element.io>

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

HarHarLinks · 2025-08-11T14:19:29Z

Results from testing session:

Upgrading an invite-only room does not invite the member users. Former room members get strange errors in Element X if they are not invited as the try to click the button in the old room.

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

HarHarLinks · 2025-08-11T15:21:55Z

Huuuge thanks to all involved: the T&S WGs contributing to the collection of info at #2704, @davidmehren for co-working heavily on reviews at the #WHY2025 chaos-DACH co-working office, @thibaultamartin and @jimmackenzie from the Foundation side, all other reviewers not visible here, and all client developers contributing info about their feature level here or elsewhere.

TheOneWithTheBraid · 2025-08-12T17:02:31Z

content/docs/communities/administration/_index.md

+- Quaternion
+- FluffyChat
+- Cinny
+


< polycule > supports the same syntax as well.

TheOneWithTheBraid · 2025-08-12T17:02:51Z

content/docs/communities/administration/_index.md

+- Cinny
+- Tammy
+- Nheko
+


< polycule > can tombstone into new rooms as well.

add the outline

098c272

Co-Authored-By: Cat <catalanlover@protonmail.com> Co-Authored-By: Gnuxie <Gnuxie@protonmail.com> Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

HarHarLinks added guides Issues related to existing guides (or guides in general if labeled before 2023) help wanted Issues we consider that external contributes can help us with. labels Aug 6, 2025

add headings and list of clients with known support

95d9edd

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

hughns reviewed Aug 7, 2025

View reviewed changes

content/docs/communities/administration/_index.md Outdated Show resolved Hide resolved

TobiasFella reviewed Aug 7, 2025

View reviewed changes

content/docs/communities/administration/_index.md Outdated Show resolved Hide resolved

content/docs/communities/administration/_index.md Outdated Show resolved Hide resolved

HarHarLinks and others added 6 commits August 8, 2025 12:38

Update info about NeoChat

e3d372f

Co-authored-by: Tobias Fella <9750016+TobiasFella@users.noreply.github.com>

formulate what is a room upgrade

718ff9a

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

format the client support list

34f5759

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

mention sidegrades

0b58c80

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

how to, v1

c21ea2a

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

how to, v2

dbc7413

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

HarHarLinks commented Aug 9, 2025

View reviewed changes

content/docs/communities/administration/_index.md Outdated Show resolved Hide resolved

HarHarLinks added 9 commits August 9, 2025 18:09

intro to recommendations

77888f3

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

recommendations right account

49623b6

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

rest of recommendations

e2eed76

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

update how

cfd833e

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

formatting

f0cae23

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

add tools and references

f4a6ebf

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

add Element Web screenshot

09f28ac

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

remove the later content

4bb64d2

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

simplified room v12 section

29f393c

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

HarHarLinks requested a review from jimmackenzie August 10, 2025 18:51

HarHarLinks marked this pull request as ready for review August 10, 2025 18:51

HarHarLinks requested a review from thibaultamartin August 10, 2025 18:52

Gnuxie reviewed Aug 10, 2025

View reviewed changes

content/docs/communities/administration/_index.md Outdated Show resolved Hide resolved

thibaultamartin approved these changes Aug 11, 2025

View reviewed changes

davidmehren reviewed Aug 11, 2025

View reviewed changes

jimmackenzie approved these changes Aug 11, 2025

View reviewed changes

HarHarLinks and others added 3 commits August 11, 2025 13:57

Apply simple suggestions from code review

35adfcd

Co-authored-by: David Mehren <git@herrmehren.de> Co-authored-by: Thibault Martin <thibaultamartin@users.noreply.github.com>

Apply suggestions from code review

6925120

Co-authored-by: Jim Mackenzie <jimm@element.io>

Apply suggestions from code review

17925b9

Co-authored-by: Jim Mackenzie <jimm@element.io>

KitsuneRal reviewed Aug 11, 2025

View reviewed changes

content/docs/communities/administration/_index.md Show resolved Hide resolved

content/docs/communities/administration/_index.md Show resolved Hide resolved

HarHarLinks and others added 4 commits August 11, 2025 15:05

fix headings

b06060f

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

Add Quaternion to the client list

e785cf9

Co-authored-by: Alexey Rusakov <Kitsune-Ral@users.sf.net>

Apply suggestions from code review

64332f4

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> Co-authored-by: Jim Mackenzie <jimm@element.io>

add more clients

8b094f0

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

final review

f4becf0

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

davidmehren approved these changes Aug 11, 2025

View reviewed changes

HarHarLinks merged commit 03645d1 into main Aug 11, 2025
3 checks passed

HarHarLinks deleted the HarHarLinks/room-upgrading-guide branch August 11, 2025 15:18

TheOneWithTheBraid reviewed Aug 12, 2025

View reviewed changes

Uh oh!

Add room upgrading guide #2861

Add room upgrading guide #2861

Uh oh!

Conversation

HarHarLinks commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HarHarLinks commented Aug 6, 2025

Uh oh!

cloudflare-workers-and-pages bot commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying matrix-website with Cloudflare Pages

Uh oh!

jimmackenzie commented Aug 6, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

HarHarLinks commented Aug 10, 2025

Uh oh!

Uh oh!

cyb3rko commented Aug 11, 2025

Uh oh!

HarHarLinks commented Aug 11, 2025

Uh oh!

thibaultamartin left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davidmehren Aug 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jimmackenzie commented Aug 11, 2025

Uh oh!

jimmackenzie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

KitsuneRal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

HarHarLinks commented Aug 11, 2025

Uh oh!

Uh oh!

HarHarLinks commented Aug 11, 2025

Uh oh!

TheOneWithTheBraid Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

TheOneWithTheBraid Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

HarHarLinks commented Aug 6, 2025 •

edited

Loading

cloudflare-workers-and-pages bot commented Aug 6, 2025 •

edited

Loading

thibaultamartin left a comment •

edited

Loading