From 256ad01fd231945be01e1d2e18fb597e2780c595 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Fri, 10 Aug 2018 16:51:44 +0100
Subject: [PATCH 1/8] proposal for room version upgrades

---
 proposals/1501-room-version-upgrades.md | 346 ++++++++++++++++++++++++
 proposals/1501-split-dag.png            | Bin 0 -> 21104 bytes
 2 files changed, 346 insertions(+)
 create mode 100644 proposals/1501-room-version-upgrades.md
 create mode 100644 proposals/1501-split-dag.png

diff --git a/proposals/1501-room-version-upgrades.md b/proposals/1501-room-version-upgrades.md
new file mode 100644
index 00000000..2fd880ea
--- /dev/null
+++ b/proposals/1501-room-version-upgrades.md
@@ -0,0 +1,346 @@
+# Room version upgrades
+
+## Background
+
+[MSC1425](https://github.com/matrix-org/matrix-doc/issues/1425) introduces a
+mechanism for associating a "version" with a room, which allows us to introduce
+changes to the mechanics of rooms.
+
+Assuming that a given change is successful, the next challenge is to introduce
+it to existing rooms. This proposal introduces a mechanism for doing so.
+
+## Proposal
+
+In short: room upgrades are implemented by creating a new room, shutting down
+the old one, and linking between the two.
+
+The mechanics of this are as follows. When Alice upgrades a room, her client
+hits a new C-S api:
+
+```
+POST /_matrix/client/r0/room/{roomId}/upgrade
+```
+```json
+{
+    "new_version": "2"
+}
+```
+
+Response:
+
+```json
+{
+    "replacement_room": "!QtykxKocfsgujksjgd:matrix.org"
+}
+```
+
+When this is called, the server:
+
+ * Checks that Alice has permissions to send `m.room.tombstone` state events.
+
+ * Creates a replacement room, with an `m.room.create` with a `predecessor` field
+   which links to the last known event in the old room:
+
+   ```json
+   {
+       "sender": "@alice:somewhere.com",
+       "type": "m.room.create",
+       "state_key": "",
+       "room_id": "!QtykxKocfsgujksjgd:matrix.org",
+       "content": {
+           "predecessor": {
+               "room_id": "!cURbaf:matrix.org",
+               "event_id": "$1235135aksjgdkg:matrix.org"
+           }
+       }
+   }
+   ```
+
+ * Replicates PL/privacy/topic/etc settings to the new room.
+
+ * Moves any local aliases to the new room.
+
+ * Sends an `m.room.tombstone` state event in the old room to tell participants
+   that it is dead:
+
+   ```json
+   {
+       "sender": "@alice:somewhere.com",
+       "type": "m.room.tombstone",
+       "state_key": "",
+       "room_id": "!cURbaf:matrix.org",
+       "content": {
+           "body": "This room has been replaced",
+           "replacement_room": "!QtykxKocfsgujksjgd:matrix.org"
+       }
+   }
+   ```
+
+ * Assuming Alice has the powers to do so, sets the power levels in the old
+   room to stop people speaking. [TODO: what does this actually mean?]
+
+Bob's client understands the `m.room.tombstone` event, and:
+
+ * Hides the old room in the room list (the room continues to be accessible
+   via the old room id (permalinks, backlinks from the new room, etc).
+
+ * Displays, at the very bottom of the timeline of the old room: "This room
+   has been upgraded. Click here to follow the conversation to the new room".
+   The link is simply a permalink to the new room. When Bob opens it, he will
+   get joined to the new room.
+
+   [Note that if Bob is on a version of synapse which doesn't understand room
+   versions, following the permalink will take him to a room view which churns
+   for a while and eventually fails. Synapse 0.33.3 / 0.34.0 should at least
+   give a sensible error code.]
+
+ * Optional extension: if the user is in both rooms, then the "N unread
+   messages" banner when scrolled up in the old room could be made to track
+   messages in the new room (so in practice the user would only ever see the
+   hiatus between the versions if they scrolled all the way to the beginning
+   of the new room or the end of the old one.)
+
+Bob's client also understands the `predecessor` field in the `m.room.create`, and:
+
+ * At the top of scrollback in the new room, displays: "This room is a
+   continuation of a previous room. Click here to see the old conversation."
+   The link is a permalink to the old room.
+
+ * Optional extensions might include things like extending room search to
+   work across two rooms.
+
+### Summary: client changes needed
+
+ * Ability for an op to view the current room version and upgrade it (by
+   hitting `/upgrade_room`).
+
+   * Also the ability for an op to see what versions the servers in the current
+     room supports (nb via a cap API) and so how many users will get locked out
+     [XXX: really? this sounds like a pita]
+
+ * Display `m.room.tombstone`s as a sticky message at the bottom of the old
+   room (perhaps replacing the message composer input) as “This room has been
+   replaced. Please click here to continue” or similar.
+
+   * When the user clicks the link, the client attempts to join the new room if
+     we are not already a member, and then switches to a view on the new room.
+
+ * If the client sees a pair of rooms with a tombstone correctly joined to the
+   new room, it should hide the old one from the RoomList.
+
+ * If one backpaginates the new room to its creation, we should show the
+   `m.room.create` as “This room is a continuation of a previous room; click here
+   to view” (or similar).
+
+ * Search is extended to search old rooms (could be done clientside for now).
+
+Future eye-candy:
+
+ * When one is viewing the old room:
+
+   * Rather than showing a sticky tombstone at the bottom, one should probably
+     have the “10 unread messages” section in the status bar which refers to
+     the current version of the room.
+
+   * We should probably also show the membership list of the current room. (Perhaps?)
+
+### Problems
+
+ * If Bob is on a remote server, how does it know where to send the
+   `/make_join` for the new room?
+
+   * We could send it to the server which sent the `tombstone` evnent? (This
+     would require the client to set the `server_name` param on the `/join`
+     request, but that seems fine)
+
+ * What about invite-only rooms? Users in the old room won't be able to join
+   the new room without an invite.
+
+   * For local users, we need to first create an invite for each user in the
+     room. This is easy, if a bit high-overhead.
+
+   * For remote users:
+
+     * Alice's server could send invites; however this is likely to give an
+       unsatisfactory UX due to servers being offline, maybe not supporting the
+       new room version, and then spamming Bob with mysterious invites.
+
+     * We could change the auth rules to treat a membership of the old room as
+       equivalent to an invite to the new room. However, this is likely to
+       reintroduce the problems we are trying to solve by replacing the room in
+       the first place.
+
+     * We could create a new type of membership which acts like an invite for
+       the purposes of allowing users into invite-only rooms, but doesn't need
+       to be sent to remote servers.
+
+ * What about clients that don't understand tombstones?
+
+   * I think they'll just show you two separate rooms (both with the same
+     name), and you won't be able to talk in one of them. It's not great but it
+     will probably do.
+
+ * It's a shame that scrollback in the new room will show a load of joins
+   before you get to the link to the old room.
+
+ * Do users stay members of the old room forever? Do they leave after a
+   respectful period? Do they leave if the user leaves the new room?
+
+## Dismissed solutions
+
+### Variations on this proposal
+
+#### Have servers auto-join their users on upgrade
+
+In order to make the upgrade more seamless, it might be good for servers to
+automatically join any users that were in the old room to the new room.
+
+In short, when Bob's server receives a tombstone event, it would attempt to
+auto-join Bob to the new room, and updates any aliases it may have to point to
+the new room.
+
+It's worth noting that the join may not be successful: for example, because
+Bob's server is too old, or because Bob has been blocked from joining the new
+room, or because joins are generally flaky. In this case Bob might attempt a
+rejoin via his client.
+
+#### Have servers merge old and new rooms together
+
+Instead of expecting clients to interpret tombstone events, servers could merge
+/sync results together for the two rooms and present both as the old room in
+/sync results - and then map from the old room ID back to the new one for API
+calls.
+
+(Note that doing this the other way around (mapping both rooms into the *new*
+room ID) doesn't really work without massively confusing clients which have
+cached data about the old room.)
+
+This sounds pretty confusing though: would the server do this forever
+for all users on the server?
+
+#### have clients merge old and new rooms
+
+At the top of scrollback for the new room, shows some sort of "messages from a
+previous version of this room" divider, above which it shows messages from the
+old room <sup name="a10">[1](#f10)</sup>.
+
+This gets quite messy quite quickly. For instance, it will be confusing to see
+any ongoing traffic in the old room (people whose servers didn't get the memo
+about the tombstone; people leaving the old room; etc). Ultimately it's all
+client polish though, so we can consider this for the future.
+
+<b name="f10">1</b> It's probably worth noting that this alone is a somewhat
+fundamental reworking of a bunch of complicated stuff in matrix-react-sdk (and
+presumably likewise in the mobile clients). [↩](#a10)
+
+### Counter-proposal: upgrade existing rooms in-place
+
+The general idea here is to divide the room DAG into v1 and v2 parts. Servers
+which do not support v2 will not see the v2 part of the DAG. This might look
+like the below:
+
+![dag](1501-split-dag.png)
+
+In this model, room version is tracked as a state event:
+
+```json
+{
+    "type": "m.room.version",
+    "content": {
+        "version": 2
+    }
+}
+```
+
+This event can only ever be sent by the **original room creator** - i.e., the
+sender of the `m.room.create event` - even if the `m.room.power_levels` say
+otherwise <sup name="a1">[1](#f1)</sup> <sup name="a2">[2](#f2)</sup>.
+
+The DAG is now divided into parts where the state of m.room.version is 2, and
+those where it is missing (and therefore implicitly 1).
+
+When sending out federation transactions, v2 events are listed under a new
+versioned_pdus key in the /send request:
+
+```
+PUT /_matrix/federation/v1/send/991079979
+
+{
+ "origin_server_ts": 1404835423000,
+ "origin": "matrix.org",
+ "pdus": [],
+ "versioned_pdus": {
+   2: [...]
+ },
+ "edus": [...]
+}
+```
+
+Old servers which do not support v2 will therefore not receive any v2 parts of
+the DAG, and transactions which only contain updates to the v2 part of the DAG
+will be treated as no-ops. Servers should ignore entries under versioned_pdus
+which correspond to versions they do not know about.
+
+As a special case, `m.room_version events` themselves are treated as having the
+version previously in force in the room, unless that was v1, in which case,
+they are treated as being v2. This means that the upgrade from v1 to v2, *and*
+the upgrade from v2 to v3, are included under `versioned_pdus[2]`, but the
+upgrade from v3 to v4 is included under `versioned_pdus[3]`. If a server
+receives an `m.room_version` event with a version it does not understand, it
+must refuse to allow any other events into the upgraded part of the DAG (and
+probably *should* refuse to allow any events into the DAG at all)
+<sup name="a1">[3](#f3)</sup>. The reasons for this are as follows:
+
+ * We want to ensure that v1-only servers do not receive the room_version
+   event, since they don't know how to auth it correctly, and more importantly
+   we want to ensure that they can't get hold of it to construct bits of DAG
+   which refer to it, and would have to follow the v2 rules.
+
+ * However, putting subsequent upgrades in a place where older servers will see
+   it means that we can do more graceful upgrades in future by telling their
+   clients that the room seems to have been upgraded.
+
+As normal, we require joining servers to declare their support for room
+versions, and reject any which do not include the version of the room given by
+the current room state.
+
+In theory this is all that is required to ensure that v1-only servers never see
+any v2 parts of the DAG (events are only sent via /send, and a v1 server should
+have no way to reference v2 parts of the DAG); however we may want to consider
+adding a "versions" parameter to API calls like /event and /state which allow a
+server to specify an event_id to fill from, in case a (non-synapse, presumably)
+implementation gets an event id from a /context request or similar and tries to
+fill from it.
+
+The experience for clients could be improved by awareness of the m.room.version
+event and querying a capabilities API (e.g. /versions?) to determine whether a
+room has been upgraded newer than the server can support.  If so, a client
+could say: “Your server must be upgraded to continue to participate in this
+room” (and manually prevent the user from trying to speak).
+
+#### Problems
+
+ * This leaves users on old v1-only servers in their own view of the room,
+   potentially continuing to speak but only seeing a subset of events (those
+   from their own and other v1 servers).
+
+   In the worst case, they might ask questions which those on v2 servers can see but have no way of replying to.
+
+   One way to mitigate this would be to ensure that the last event sent in the
+   v1 part of the DAG is an m.room.power_levels to make the room read-only to
+   casual users; then restore the situation in the v2 DAG.
+
+ * There's nothing to stop "inquisitive" users on v1 servers sending
+   m.room.version events, which is likely to completely split-brain the room.
+
+ * This doesn't help us do things like change the format of the room id.
+
+<b name="f1">1</b> This avoids the version event itself being vulnerable to state
+resets. [↩](#a1)
+
+<b name="f2">2</b> This is therefore a change to the event authorisation rules
+which we need to introduce with room version 2. [↩](#a2)
+
+<b name="f3">3</b> It's worth noting this does give the room creator a
+kill-switch for the room, even if they've subsequently been de-opped. Such is
+life. [↩](#a3)
diff --git a/proposals/1501-split-dag.png b/proposals/1501-split-dag.png
new file mode 100644
index 0000000000000000000000000000000000000000..73312e5a4488ea254e510d0b9a0b531d434026e8
GIT binary patch
literal 21104
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
Hx<&sB3qj7t

literal 0
HcmV?d00001


From 16072538f074a631737b49408af7dd07265f8eb2 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Mon, 13 Aug 2018 16:57:51 +0100
Subject: [PATCH 2/8] s/settings/events

---
 proposals/1501-room-version-upgrades.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposals/1501-room-version-upgrades.md b/proposals/1501-room-version-upgrades.md
index 2fd880ea..7e74a3d9 100644
--- a/proposals/1501-room-version-upgrades.md
+++ b/proposals/1501-room-version-upgrades.md
@@ -56,7 +56,7 @@ When this is called, the server:
    }
    ```
 
- * Replicates PL/privacy/topic/etc settings to the new room.
+ * Replicates PL/privacy/topic/etc events to the new room.
 
  * Moves any local aliases to the new room.
 

From 5455cc4e4f64f9917e913f3f2e5a695165bb6298 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Mon, 20 Aug 2018 13:48:24 +0100
Subject: [PATCH 3/8] fix endpoint path

---
 proposals/1501-room-version-upgrades.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposals/1501-room-version-upgrades.md b/proposals/1501-room-version-upgrades.md
index 7e74a3d9..416082d4 100644
--- a/proposals/1501-room-version-upgrades.md
+++ b/proposals/1501-room-version-upgrades.md
@@ -18,7 +18,7 @@ The mechanics of this are as follows. When Alice upgrades a room, her client
 hits a new C-S api:
 
 ```
-POST /_matrix/client/r0/room/{roomId}/upgrade
+POST /_matrix/client/r0/rooms/{roomId}/upgrade
 ```
 ```json
 {

From 4750b297b35f64a72a155066f4161e46d483824a Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Tue, 28 Aug 2018 11:33:07 +0100
Subject: [PATCH 4/8] s/upgrade_room/upgrade

---
 proposals/1501-room-version-upgrades.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposals/1501-room-version-upgrades.md b/proposals/1501-room-version-upgrades.md
index 416082d4..c4850384 100644
--- a/proposals/1501-room-version-upgrades.md
+++ b/proposals/1501-room-version-upgrades.md
@@ -112,7 +112,7 @@ Bob's client also understands the `predecessor` field in the `m.room.create`, an
 ### Summary: client changes needed
 
  * Ability for an op to view the current room version and upgrade it (by
-   hitting `/upgrade_room`).
+   hitting `/upgrade`).
 
    * Also the ability for an op to see what versions the servers in the current
      room supports (nb via a cap API) and so how many users will get locked out

From 97eaa189a078e808ff2edca4ab890ea52b221efb Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Wed, 17 Oct 2018 12:00:52 +0100
Subject: [PATCH 5/8] A couple of minor tweaks and clarifications

Clarification about what we're doing with the `power_levels`. Restructure
slightly to fit better with the standard MSC template.
---
 proposals/1501-room-version-upgrades.md | 58 +++++++++++++++----------
 1 file changed, 36 insertions(+), 22 deletions(-)

diff --git a/proposals/1501-room-version-upgrades.md b/proposals/1501-room-version-upgrades.md
index c4850384..37eeb592 100644
--- a/proposals/1501-room-version-upgrades.md
+++ b/proposals/1501-room-version-upgrades.md
@@ -77,8 +77,9 @@ When this is called, the server:
    ```
 
  * Assuming Alice has the powers to do so, sets the power levels in the old
-   room to stop people speaking. [TODO: what does this actually mean?]
-
+   room to stop people speaking. In practice, this means setting
+   `events_default` and `invite` to the greater of `50` and `users_default+1`.
+   
 Bob's client understands the `m.room.tombstone` event, and:
 
  * Hides the old room in the room list (the room continues to be accessible
@@ -91,8 +92,8 @@ Bob's client understands the `m.room.tombstone` event, and:
 
    [Note that if Bob is on a version of synapse which doesn't understand room
    versions, following the permalink will take him to a room view which churns
-   for a while and eventually fails. Synapse 0.33.3 / 0.34.0 should at least
-   give a sensible error code.]
+   for a while and eventually fails. Synapse 0.33.3 should at least give a
+   sensible error code.]
 
  * Optional extension: if the user is in both rooms, then the "N unread
    messages" banner when scrolled up in the old room could be made to track
@@ -109,14 +110,14 @@ Bob's client also understands the `predecessor` field in the `m.room.create`, an
  * Optional extensions might include things like extending room search to
    work across two rooms.
 
-### Summary: client changes needed
+### Client changes needed
 
  * Ability for an op to view the current room version and upgrade it (by
    hitting `/upgrade`).
 
-   * Also the ability for an op to see what versions the servers in the current
-     room supports (nb via a cap API) and so how many users will get locked out
-     [XXX: really? this sounds like a pita]
+   * ~~Also the ability for an op to see what versions the servers in the
+     current room supports (nb via a cap API) and so how many users will get
+     locked out~~ (This is descoped for now.)
 
  * Display `m.room.tombstone`s as a sticky message at the bottom of the old
    room (perhaps replacing the message composer input) as “This room has been
@@ -125,6 +126,9 @@ Bob's client also understands the `predecessor` field in the `m.room.create`, an
    * When the user clicks the link, the client attempts to join the new room if
      we are not already a member, and then switches to a view on the new room.
 
+     The client should supply the name of the server which sent the tombstone
+     event as the `server_name` for the `/join` request.
+
  * If the client sees a pair of rooms with a tombstone correctly joined to the
    new room, it should hide the old one from the RoomList.
 
@@ -144,22 +148,24 @@ Future eye-candy:
 
    * We should probably also show the membership list of the current room. (Perhaps?)
 
-### Problems
+## Future extensions
 
- * If Bob is on a remote server, how does it know where to send the
-   `/make_join` for the new room?
+### Invite-only rooms
 
-   * We could send it to the server which sent the `tombstone` evnent? (This
-     would require the client to set the `server_name` param on the `/join`
-     request, but that seems fine)
+Invite-only rooms are not dealt with explicitly here; they are made tricky by
+the fact that users in the old room won't be able to join the new room without
+an invite.
 
- * What about invite-only rooms? Users in the old room won't be able to join
-   the new room without an invite.
+For now, we are assuming that the main reasons for carrying out a room-version
+upgrade (ie, security problems due to state resets and the like) do not apply
+as strongly to invite-only rooms, and we have descoped them for now.
 
-   * For local users, we need to first create an invite for each user in the
-     room. This is easy, if a bit high-overhead.
+In future, we will most likely deal with them as follows:
 
-   * For remote users:
+ * For local users, we need to first create an invite for each user in the
+   room. This is easy, if a bit high-overhead.
+
+ * For remote users:
 
      * Alice's server could send invites; however this is likely to give an
        unsatisfactory UX due to servers being offline, maybe not supporting the
@@ -174,6 +180,17 @@ Future eye-candy:
        the purposes of allowing users into invite-only rooms, but doesn't need
        to be sent to remote servers.
 
+### Parting users from the old room
+
+It's not obvious if users should stay members of the old room indefinitely
+(until they manually leave). Perhaps they should automatically leave after a
+respectful period? What if the user leaves the *new* room?
+
+For now, we'll assume that they stay members until they manually leave. We can
+see how that feels in practice.
+
+## Potential issues
+
  * What about clients that don't understand tombstones?
 
    * I think they'll just show you two separate rooms (both with the same
@@ -183,9 +200,6 @@ Future eye-candy:
  * It's a shame that scrollback in the new room will show a load of joins
    before you get to the link to the old room.
 
- * Do users stay members of the old room forever? Do they leave after a
-   respectful period? Do they leave if the user leaves the new room?
-
 ## Dismissed solutions
 
 ### Variations on this proposal

From b5e5a690f573b247237ec5e136519ef2a691bf35 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Wed, 17 Oct 2018 17:28:34 +0100
Subject: [PATCH 6/8] add version to example m.room.create event

---
 proposals/1501-room-version-upgrades.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/proposals/1501-room-version-upgrades.md b/proposals/1501-room-version-upgrades.md
index 37eeb592..55af3341 100644
--- a/proposals/1501-room-version-upgrades.md
+++ b/proposals/1501-room-version-upgrades.md
@@ -48,6 +48,7 @@ When this is called, the server:
        "state_key": "",
        "room_id": "!QtykxKocfsgujksjgd:matrix.org",
        "content": {
+           "version": "2",
            "predecessor": {
                "room_id": "!cURbaf:matrix.org",
                "event_id": "$1235135aksjgdkg:matrix.org"

From 14b98a02203b913956d876c1b00f406ba047b65a Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Wed, 17 Oct 2018 20:28:53 +0100
Subject: [PATCH 7/8] A couple of clarifications

- the body of the tombstone is defined by the server.
- the client can follow tombstones until it finds a live room
---
 proposals/1501-room-version-upgrades.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/proposals/1501-room-version-upgrades.md b/proposals/1501-room-version-upgrades.md
index 55af3341..fc0bf71e 100644
--- a/proposals/1501-room-version-upgrades.md
+++ b/proposals/1501-room-version-upgrades.md
@@ -77,10 +77,13 @@ When this is called, the server:
    }
    ```
 
+   The `body` of the tombstone event is defined by the server (for now, at
+   least).
+
  * Assuming Alice has the powers to do so, sets the power levels in the old
    room to stop people speaking. In practice, this means setting
    `events_default` and `invite` to the greater of `50` and `users_default+1`.
-   
+
 Bob's client understands the `m.room.tombstone` event, and:
 
  * Hides the old room in the room list (the room continues to be accessible
@@ -96,6 +99,10 @@ Bob's client understands the `m.room.tombstone` event, and:
    for a while and eventually fails. Synapse 0.33.3 should at least give a
    sensible error code.]
 
+   If it turns out that the replacement room also has a tombstone event, the
+   client may automatically keep following the chain until it reaches a room
+   that isn't dead.
+
  * Optional extension: if the user is in both rooms, then the "N unread
    messages" banner when scrolled up in the old room could be made to track
    messages in the new room (so in practice the user would only ever see the

From 21a45948caebd1bf15d6d39d8932accbd65765ff Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Mon, 22 Oct 2018 17:03:48 +0100
Subject: [PATCH 8/8] Explain rationale for setting server_name when joining
 upgraded room

---
 proposals/1501-room-version-upgrades.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/proposals/1501-room-version-upgrades.md b/proposals/1501-room-version-upgrades.md
index fc0bf71e..3a726250 100644
--- a/proposals/1501-room-version-upgrades.md
+++ b/proposals/1501-room-version-upgrades.md
@@ -135,7 +135,9 @@ Bob's client also understands the `predecessor` field in the `m.room.create`, an
      we are not already a member, and then switches to a view on the new room.
 
      The client should supply the name of the server which sent the tombstone
-     event as the `server_name` for the `/join` request.
+     event as the `server_name` for the `/join` request. (That being the most
+     likely server to have an up-to-date copy of the room - this is essentially
+     a workaround for [vector-im/riot-web#2925](https://github.com/vector-im/riot-web/issues/2925).)
 
  * If the client sees a pair of rooms with a tombstone correctly joined to the
    new room, it should hide the old one from the RoomList.