From cd6b012523c5ea11974617036ec1ee189babdb99 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 17:07:49 -0600 Subject: [PATCH 1/3] Clarify what a "module" is and update feature profiles for clients Fixes https://github.com/matrix-org/matrix-doc/issues/2009 --- .../newsfragments/2098.clarification | 1 + specification/feature_profiles.rst | 36 ++++++++++++++++++- specification/modules.rst | 8 +++++ specification/modules/_template.rst | 2 +- 4 files changed, 45 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2098.clarification diff --git a/changelogs/client_server/newsfragments/2098.clarification b/changelogs/client_server/newsfragments/2098.clarification new file mode 100644 index 000000000..1c8ba3ea7 --- /dev/null +++ b/changelogs/client_server/newsfragments/2098.clarification @@ -0,0 +1 @@ +Clarify what a "module" is and update feature profiles for clients. diff --git a/specification/feature_profiles.rst b/specification/feature_profiles.rst index c6b8ef4c0..bb6383807 100644 --- a/specification/feature_profiles.rst +++ b/specification/feature_profiles.rst @@ -1,4 +1,5 @@ .. Copyright 2016 OpenMarket Ltd +.. Copyright 2019 The Matrix.org Foundation C.I.C. .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -32,33 +33,67 @@ Summary Module / Profile Web Mobile Desktop CLI Embedded ===================================== ========== ========== ========== ========== ========== `Instant Messaging`_ Required Required Required Required Optional + `Direct Messaging`_ Required Required Required Required Optional + `Mentions`_ Required Required Required Optional Optional `Presence`_ Required Required Required Required Optional `Push Notifications`_ Optional Required Optional Optional Optional `Receipts`_ Required Required Required Required Optional + `Fully read markers`_ Optional Optional Optional Optional Optional `Typing Notifications`_ Required Required Required Required Optional `VoIP`_ Required Required Required Optional Optional + `Ignoring Users`_ Required Required Required Optional Optional + `Reporting Content`_ Optional Optional Optional Optional Optional `Content Repository`_ Required Required Required Optional Optional `Managing History Visibility`_ Required Required Required Required Optional `Server Side Search`_ Optional Optional Optional Optional Optional + `Room Upgrades`_ Required Required Required Required Optional `Server Administration`_ Optional Optional Optional Optional Optional `Event Context`_ Optional Optional Optional Optional Optional `Third Party Networks`_ Optional Optional Optional Optional Optional + `Send-to-Device Messaging`_ Optional Optional Optional Optional Optional + `Device Management`_ Optional Optional Optional Optional Optional + `End-to-End Encryption`_ Optional Optional Optional Optional Optional + `Guest Accounts`_ Optional Optional Optional Optional Optional + `Room Previews`_ Optional Optional Optional Optional Optional + `Client Config`_ Optional Optional Optional Optional Optional + `SSO Login`_ Optional Optional Optional Optional Optional + `OpenID`_ Optional Optional Optional Optional Optional + `Stickers`_ Optional Optional Optional Optional Optional + `Server ACLs`_ Optional Optional Optional Optional Optional + `Server Notices`_ Optional Optional Optional Optional Optional ===================================== ========== ========== ========== ========== ========== *Please see each module for more details on what clients need to implement.* .. _Instant Messaging: `module:im`_ +.. _Direct Messaging: `module:dm`_ +.. _Mentions: `module:mentions`_ .. _Presence: `module:presence`_ .. _Push Notifications: `module:push`_ .. _Receipts: `module:receipts`_ +.. _Fully read markers: `module:read-markers`_ .. _Typing Notifications: `module:typing`_ .. _VoIP: `module:voip`_ +.. _Ignoring Users: `module:ignore_users`_ +.. _Reporting Content: `module:report_content`_ .. _Content Repository: `module:content`_ .. _Managing History Visibility: `module:history-visibility`_ .. _Server Side Search: `module:search`_ +.. _Room Upgrades: `module:room-upgrades`_ .. _Server Administration: `module:admin`_ .. _Event Context: `module:event-context`_ .. _Third Party Networks: `module:third-party-networks`_ +.. _Send-to-Device Messaging: `module:to_device`_ +.. _Device Management: `module:device-management`_ +.. _End-to-End Encryption: `module:e2e`_ +.. _Guest Accounts: `module:guest-access`_ +.. _Room Previews: `module:room-previews`_ +.. _Client Config: `module:account_data`_ +.. _SSO Login: `module:sso_login`_ +.. _OpenID: `module:openid`_ +.. _Stickers: `module:stickers`_ +.. _Server ACLs: `module:server-acls`_ +.. Server Notices already has a link elsewhere. Clients ------- @@ -110,4 +145,3 @@ This is a client which is typically running on an embedded device such as a kettle, fridge or car. These clients tend to perform a few operations and run in a resource constrained environment. Like embedded applications, they are not intended to be fully-fledged communication systems. - diff --git a/specification/modules.rst b/specification/modules.rst index 36f79cfd8..f2269a5a4 100644 --- a/specification/modules.rst +++ b/specification/modules.rst @@ -1,4 +1,5 @@ .. Copyright 2016 OpenMarket Ltd +.. Copyright 2019 The Matrix.org Foundation C.I.C. .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -15,3 +16,10 @@ Modules ======= +Modules are parts of the Client-Server API which are not universal to all +endpoints and are accessible to all clients. Modules are strictly defined +within this specification and should not be mistaken for XEP or equivalent +extensions from other protocols - in order for an implementation to be +compliant with the Client-Server specification it MUST support all modules +and supporting specification. The exception being clients, which are governed +by `Feature Profiles <#feature-profiles>`_. diff --git a/specification/modules/_template.rst b/specification/modules/_template.rst index aa4f93db2..d1fef7f5f 100644 --- a/specification/modules/_template.rst +++ b/specification/modules/_template.rst @@ -15,6 +15,7 @@ Module Heading ============== +.. NOTE: Prefer to identify-modules-with-dashes despite historical examples. .. _module:short-name: A short summary of the module. What features does this module provide? An anchor @@ -67,4 +68,3 @@ This includes privacy leaks: for example leaking presence info. How do misbehaving clients or servers impact this module? This section should always be included, if only to say "we've thought about it but there isn't anything to do here". - From 87d8d970745e107f4494256dcbe475fa2c73eda3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 17:19:08 -0600 Subject: [PATCH 2/3] Remove incomplete and weird sentence --- specification/modules.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/specification/modules.rst b/specification/modules.rst index f2269a5a4..6a2564ce0 100644 --- a/specification/modules.rst +++ b/specification/modules.rst @@ -17,9 +17,8 @@ Modules ======= Modules are parts of the Client-Server API which are not universal to all -endpoints and are accessible to all clients. Modules are strictly defined -within this specification and should not be mistaken for XEP or equivalent -extensions from other protocols - in order for an implementation to be -compliant with the Client-Server specification it MUST support all modules -and supporting specification. The exception being clients, which are governed -by `Feature Profiles <#feature-profiles>`_. +endpoints. Modules are strictly defined within this specification and +should not be mistaken for XEP or equivalent extensions from other protocols +- in order for an implementation to be compliant with the Client-Server +specification it MUST support all modules and supporting specification. +The exception being clients, which are governed by `Feature Profiles <#feature-profiles>`_. From 06ee60f0046b80d7d85f80e1b23d2c2e1147d0cd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 17:32:59 -0600 Subject: [PATCH 3/3] Clarify what compliant implementations are --- specification/modules.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/specification/modules.rst b/specification/modules.rst index 6a2564ce0..1bc884459 100644 --- a/specification/modules.rst +++ b/specification/modules.rst @@ -18,7 +18,10 @@ Modules Modules are parts of the Client-Server API which are not universal to all endpoints. Modules are strictly defined within this specification and -should not be mistaken for XEP or equivalent extensions from other protocols -- in order for an implementation to be compliant with the Client-Server -specification it MUST support all modules and supporting specification. -The exception being clients, which are governed by `Feature Profiles <#feature-profiles>`_. +should not be mistaken for experimental extensions or optional features. +A compliant server implementation MUST support all modules and supporting +specification (unless the implementation only targets clients of certain +profiles, in which case only the required modules for those feature profiles +MUST be implemented). A compliant client implementation MUST support all +the required modules and supporting specification for the `Feature Profile <#feature-profiles>`_ +it targets.