From ccc1cdaeadd5a207cc3f23c938e46512e994204b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 7 Jan 2019 14:38:21 -0700 Subject: [PATCH 1/4] Add support for unstable feature advertising via /versions Incorporates https://github.com/matrix-org/matrix-doc/issues/1497 --- api/client-server/versions.yaml | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/api/client-server/versions.yaml b/api/client-server/versions.yaml index d3aa035947c..4d0fd49e8d0 100644 --- a/api/client-server/versions.yaml +++ b/api/client-server/versions.yaml @@ -33,13 +33,25 @@ paths: Only the latest ``Z`` value will be reported for each supported ``X.Y`` value. i.e. if the server implements ``r0.0.0``, ``r0.0.1``, and ``r1.2.0``, it will report ``r0.0.1`` and ``r1.2.0``. + + The server may additionally advertise experimental features it supports + through ``unstable_features``. These features should be namespaced and + may optionally include version information within their name if desired. + Features listed here are not for optionally toggling parts of the Matrix + specification and should only be used to advertise support for a feature + which has not yet landed in the spec. For example, an accepted proposal + for a feature needing implementation would advertise itself here with + the intention of being removed from this list once the spec changes land. operationId: getVersions responses: 200: description: The versions supported by the server. examples: application/json: { - "versions": ["r0.0.1"] + "versions": ["r0.0.1"], + "unstable_features": { + "org.example.my_feature": true + } } schema: type: object @@ -50,5 +62,15 @@ paths: items: type: string description: The supported versions + unstable_features: + type: object + description: |- + Experimental features the server supports. Features not listed here, + or the lack of this property all together, indicate that a feature is + not supported. + additionalProperties: + type: boolean + description: Whether or not the namespaced feature is supported. + required: ['versions'] tags: - Server administration From 75c084e987d2418f0ca6b0a3a0d321cd49720ecb Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 7 Jan 2019 14:50:55 -0700 Subject: [PATCH 2/4] changelog --- changelogs/client_server/newsfragments/1786.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1786.feature diff --git a/changelogs/client_server/newsfragments/1786.feature b/changelogs/client_server/newsfragments/1786.feature new file mode 100644 index 00000000000..6f21778c006 --- /dev/null +++ b/changelogs/client_server/newsfragments/1786.feature @@ -0,0 +1 @@ +Add support for advertising experimental features to clients. From f5fa7e59241cc7d1907a11e0d194aa597f0c3439 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 17 Jan 2019 14:05:30 -0700 Subject: [PATCH 3/4] Change wording to encourage servers to make reasonable decisions --- api/client-server/versions.yaml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/api/client-server/versions.yaml b/api/client-server/versions.yaml index 4d0fd49e8d0..109e852ca38 100644 --- a/api/client-server/versions.yaml +++ b/api/client-server/versions.yaml @@ -39,9 +39,12 @@ paths: may optionally include version information within their name if desired. Features listed here are not for optionally toggling parts of the Matrix specification and should only be used to advertise support for a feature - which has not yet landed in the spec. For example, an accepted proposal - for a feature needing implementation would advertise itself here with - the intention of being removed from this list once the spec changes land. + which has not yet landed in the spec. For example, a feature currently + undergoing the proposal process may appear here and eventually be taken + off this list once the feature lands in the spec and the server deems it + reasonable to do so. Servers may wish to keep advertising features here + after they've been released into the spec to give clients a chance to + upgrade appropriately. operationId: getVersions responses: 200: From 413bfaeb68f3e9c072adf539aa54c2b6c7ee218f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 23 Jan 2019 19:03:14 -0700 Subject: [PATCH 4/4] Add clarification that clients shouldn't use unstable things as stable --- api/client-server/versions.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/client-server/versions.yaml b/api/client-server/versions.yaml index 109e852ca38..2464af1dced 100644 --- a/api/client-server/versions.yaml +++ b/api/client-server/versions.yaml @@ -44,7 +44,8 @@ paths: off this list once the feature lands in the spec and the server deems it reasonable to do so. Servers may wish to keep advertising features here after they've been released into the spec to give clients a chance to - upgrade appropriately. + upgrade appropriately. Additionally, clients should avoid using unstable + features in their stable releases. operationId: getVersions responses: 200: