From 7fee7373ea619b05c9dc325a07bc8a9d7adcb912 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 16 Jan 2019 17:32:07 -0700 Subject: [PATCH 1/5] Proposal for advertising capable room versions to clients --- .../1804-advertising-capable-room-versions.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 proposals/1804-advertising-capable-room-versions.md diff --git a/proposals/1804-advertising-capable-room-versions.md b/proposals/1804-advertising-capable-room-versions.md new file mode 100644 index 00000000..fca22409 --- /dev/null +++ b/proposals/1804-advertising-capable-room-versions.md @@ -0,0 +1,49 @@ +# Proposal for advertising capable room versions to clients + +Currently clients need to guess at which room versions the server supports, if any. This is particularly +difficult to do as it generally requires knowing the state of the ecosystem and what versions are +available and how keen users are to upgrade their servers and clients. The impossible judgement call +for when to prompt people to upgrade shouldn't be impossible, or even a judgement call. + + +## Proposal + +Building off of [MSC1753](https://github.com/matrix-org/matrix-doc/pull/1753) (capabilities API) and +the [recommendations laid out for room versions](https://github.com/matrix-org/matrix-doc/pull/1773/files#diff-1436075794bb304492ca6953a6692cd0R463), +this proposal suggests a `m.room_versions` capability be introduced like the following: + +```json +{ + "capabilities": { + "m.room_versions": { + "m.development": ["state-res-v2-test", "event-ids-as-hashes-test", "3"], + "m.beta": ["2"], + "m.default": "1", + "m.recommended": "1", + "m.mandatory": ["1"] + } + } +} +``` + +The labels picked (`m.development`, etc) are based upon the categories for different room versions. +Note that `m.default` and `m.recommended` reinforce that there is exactly 1 version in each category. + +Clients are encouraged to make use of this capability to determine if the server supports a given +version, and at what state. Clients should cross-reference the versions with the room version spec +where possible. For example, if a slightly older server hasn't yet put version `2` into `m.default`, +but the spec says `2` is the new default and the client knows this, the client should treat `2` as +the new default. + +Similarly, clients should prompt room administrators (or those with enough permission) to upgrade +their rooms where possible. + + +## Potential issues + +Changes aren't pushed to the client, which means clients may want to poll this endpoint on some +heuristic instead. For example, clients may want to poll the endpoint weekly or when the user relaunches +the client. Clients may also wish to provide users a way to upgrade without considering the capabilities +of the server, expecting that the server may not support the user-provided version - the intention +being such a feature would be used by eager room administrators which do not want to relaunch their +client, for example. From 5da17d0114979e08fbbf5ab6855e1fb811266f5f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 17 Jan 2019 09:41:11 -0700 Subject: [PATCH 2/5] Remove recommendation for clients to respect the spec over the server --- proposals/1804-advertising-capable-room-versions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/1804-advertising-capable-room-versions.md b/proposals/1804-advertising-capable-room-versions.md index fca22409..924cd77f 100644 --- a/proposals/1804-advertising-capable-room-versions.md +++ b/proposals/1804-advertising-capable-room-versions.md @@ -30,10 +30,10 @@ The labels picked (`m.development`, etc) are based upon the categories for diffe Note that `m.default` and `m.recommended` reinforce that there is exactly 1 version in each category. Clients are encouraged to make use of this capability to determine if the server supports a given -version, and at what state. Clients should cross-reference the versions with the room version spec -where possible. For example, if a slightly older server hasn't yet put version `2` into `m.default`, -but the spec says `2` is the new default and the client knows this, the client should treat `2` as -the new default. +version, and at what state. + +Clients should prompt people with sufficient permissions to perform an upgrade to upgrade their rooms +to the `m.recommended` room version. Similarly, clients should prompt room administrators (or those with enough permission) to upgrade their rooms where possible. From 853d7ede30e00a52b2ed516a956769b84f197f15 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 17 Jan 2019 09:41:24 -0700 Subject: [PATCH 3/5] Clarify the categories and the interaction between them --- .../1804-advertising-capable-room-versions.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/proposals/1804-advertising-capable-room-versions.md b/proposals/1804-advertising-capable-room-versions.md index 924cd77f..7686f1b2 100644 --- a/proposals/1804-advertising-capable-room-versions.md +++ b/proposals/1804-advertising-capable-room-versions.md @@ -35,8 +35,18 @@ version, and at what state. Clients should prompt people with sufficient permissions to perform an upgrade to upgrade their rooms to the `m.recommended` room version. -Similarly, clients should prompt room administrators (or those with enough permission) to upgrade -their rooms where possible. +Room versions might appear under multiple categories under some circumstances. In particular, it is +expected that anything in `m.development` or `m.beta` appears exactly once in the whole capability +whereas `m.default`, `m.recommended`, and `m.mandatory` may duplicate a room version. The duplication +is possible due to the definitions of each category: + +* `m.default` - This is the room version that the server is going to apply to all new rooms by default. +* `m.recommended` - The version clients should be prompting people to upgrade to. +* `m.mandatory` - The version the server is going to enforce on all pre-existing rooms. + +With these definitions, it is possible that a room version fits multiple criteria (ie: "please upgrade +your rooms to version X which is also the default for new rooms"). Clients will generally only be +interested in the `m.recommended` room version, leaving the rest as informational for users. ## Potential issues From 50eba23669bf10d7b7b3f707ed11d70d51aa650a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 22 Jan 2019 18:24:04 -0700 Subject: [PATCH 4/5] Update MSC to match how room versions work As per 1773. --- .../1804-advertising-capable-room-versions.md | 38 +++++++------------ 1 file changed, 14 insertions(+), 24 deletions(-) diff --git a/proposals/1804-advertising-capable-room-versions.md b/proposals/1804-advertising-capable-room-versions.md index 7686f1b2..abcf56e9 100644 --- a/proposals/1804-advertising-capable-room-versions.md +++ b/proposals/1804-advertising-capable-room-versions.md @@ -3,7 +3,7 @@ Currently clients need to guess at which room versions the server supports, if any. This is particularly difficult to do as it generally requires knowing the state of the ecosystem and what versions are available and how keen users are to upgrade their servers and clients. The impossible judgement call -for when to prompt people to upgrade shouldn't be impossible, or even a judgement call. +for when to encourage people to upgrade shouldn't be impossible, or even a judgement call. ## Proposal @@ -16,37 +16,27 @@ this proposal suggests a `m.room_versions` capability be introduced like the fol { "capabilities": { "m.room_versions": { - "m.development": ["state-res-v2-test", "event-ids-as-hashes-test", "3"], - "m.beta": ["2"], - "m.default": "1", - "m.recommended": "1", - "m.mandatory": ["1"] + "default": "1", + "available": { + "1": "stable", + "2": "stable", + "state-res-v2-test": "unstable", + "event-ids-as-hashes": "unstable", + "3": "unstable" + } } } } ``` -The labels picked (`m.development`, etc) are based upon the categories for different room versions. -Note that `m.default` and `m.recommended` reinforce that there is exactly 1 version in each category. - Clients are encouraged to make use of this capability to determine if the server supports a given -version, and at what state. - -Clients should prompt people with sufficient permissions to perform an upgrade to upgrade their rooms -to the `m.recommended` room version. - -Room versions might appear under multiple categories under some circumstances. In particular, it is -expected that anything in `m.development` or `m.beta` appears exactly once in the whole capability -whereas `m.default`, `m.recommended`, and `m.mandatory` may duplicate a room version. The duplication -is possible due to the definitions of each category: +version, and at what level of stability. -* `m.default` - This is the room version that the server is going to apply to all new rooms by default. -* `m.recommended` - The version clients should be prompting people to upgrade to. -* `m.mandatory` - The version the server is going to enforce on all pre-existing rooms. +The default version is the version that the server is using to create new rooms with. Clients can +make the assumption that the default version is a stable version. -With these definitions, it is possible that a room version fits multiple criteria (ie: "please upgrade -your rooms to version X which is also the default for new rooms"). Clients will generally only be -interested in the `m.recommended` room version, leaving the rest as informational for users. +Clients should encourage people with sufficient permissions to perform an upgrade to upgrade their +rooms to the `default` room version when the room is using an `unstable` version. ## Potential issues From 577edeb53b7cf4dafa37b88f9d04cb90d91c6b3f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 25 Jan 2019 09:27:23 -0700 Subject: [PATCH 5/5] Say that !stable == unstable --- proposals/1804-advertising-capable-room-versions.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/1804-advertising-capable-room-versions.md b/proposals/1804-advertising-capable-room-versions.md index abcf56e9..684bd524 100644 --- a/proposals/1804-advertising-capable-room-versions.md +++ b/proposals/1804-advertising-capable-room-versions.md @@ -22,7 +22,7 @@ this proposal suggests a `m.room_versions` capability be introduced like the fol "2": "stable", "state-res-v2-test": "unstable", "event-ids-as-hashes": "unstable", - "3": "unstable" + "3": "future-scifi-label" } } } @@ -30,7 +30,8 @@ this proposal suggests a `m.room_versions` capability be introduced like the fol ``` Clients are encouraged to make use of this capability to determine if the server supports a given -version, and at what level of stability. +version, and at what level of stability. Anything not flagged explicitly as `stable` should be treated +as `unstable` (ie: `future-scifi-label` is the same as `unstable`). The default version is the version that the server is using to create new rooms with. Clients can make the assumption that the default version is a stable version.