From 10648aa9e8ce9556d3b881539acca7c9a7962156 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 22:30:37 -0600 Subject: [PATCH 1/9] Clarify that FAIL_ERROR is not limited to just homeservers. Fixes https://github.com/matrix-org/matrix-doc/issues/1735 --- changelogs/client_server/newsfragments/2036.clarification | 1 + specification/client_server_api.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2036.clarification diff --git a/changelogs/client_server/newsfragments/2036.clarification b/changelogs/client_server/newsfragments/2036.clarification new file mode 100644 index 00000000..96058b7b --- /dev/null +++ b/changelogs/client_server/newsfragments/2036.clarification @@ -0,0 +1 @@ +Clarify that ``FAIL_ERROR`` in autodiscovery is not limited to just homeservers. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index a8bbfca0..4158bad8 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -289,7 +289,7 @@ In this section, the following terms are used with specific meanings: ``FAIL_ERROR`` Inform the user that auto-discovery did not return any usable URLs. Do not continue further with the current login process. At this point, valid data - was obtained, but no homeserver is available to serve the client. No further + was obtained, but no server is available to serve the client. No further guess should be attempted and the user should make a conscientious decision what to do next. From d8eb2949066c9c53f7501da9fb86f76fa762e960 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 22:44:24 -0600 Subject: [PATCH 2/9] Fix s2s changelog entries --- changelogs/server_server/newsfragments/1904.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/server_server/newsfragments/1904.clarification b/changelogs/server_server/newsfragments/1904.clarification index 94174ebd..531fdb94 100644 --- a/changelogs/server_server/newsfragments/1904.clarification +++ b/changelogs/server_server/newsfragments/1904.clarification @@ -1 +1 @@ -Fix the `access_token` parameter in the open_id endpoint. +Fix the ``access_token`` parameter in the open_id endpoint. From 88d47fd57e423c3e2e958fc547f7ef4812eb3ca2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 22:51:52 -0600 Subject: [PATCH 3/9] Rename changelog entry to point to PR We use the PR for every other entry, so here is no exception. --- .../newsfragments/{1904.clarification => 1906.clarification} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changelogs/server_server/newsfragments/{1904.clarification => 1906.clarification} (100%) diff --git a/changelogs/server_server/newsfragments/1904.clarification b/changelogs/server_server/newsfragments/1906.clarification similarity index 100% rename from changelogs/server_server/newsfragments/1904.clarification rename to changelogs/server_server/newsfragments/1906.clarification From 572a6056ad64c5f3f654f91a27cf8a42c19d6ee5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 23:15:02 -0600 Subject: [PATCH 4/9] Clarify that login flows must be completed in order Fixes https://github.com/matrix-org/matrix-doc/issues/1134 Evidence of this being the case is shown here: https://github.com/matrix-org/synapse/pull/5174 --- changelogs/client_server/newsfragments/2042.clarification | 1 + specification/client_server_api.rst | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2042.clarification diff --git a/changelogs/client_server/newsfragments/2042.clarification b/changelogs/client_server/newsfragments/2042.clarification new file mode 100644 index 00000000..4e17b99f --- /dev/null +++ b/changelogs/client_server/newsfragments/2042.clarification @@ -0,0 +1 @@ +Clarify that login flows are meant to be completed in order. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index a8bbfca0..4b7065b3 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -406,8 +406,9 @@ an additional stage. This exchange continues until the final success. For each endpoint, a server offers one or more 'flows' that the client can use to authenticate itself. Each flow comprises a series of stages, as described -above. The client is free to choose which flow it follows. When all stages in a -flow are complete, authentication is complete and the API call succeeds. +above. The client is free to choose which flow it follows, however the flow's +stages must be completed in order. When all stages in a flow are complete, +authentication is complete and the API call succeeds. User-interactive API in the REST API <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< From bf86b4b83ca9ee97ef8bc7edcc17a663996bcffd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 23:42:08 -0600 Subject: [PATCH 5/9] Fix incorrect PR reference on changelog --- .../client_server/newsfragments/{1903.feature => 1908.feature} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changelogs/client_server/newsfragments/{1903.feature => 1908.feature} (100%) diff --git a/changelogs/client_server/newsfragments/1903.feature b/changelogs/client_server/newsfragments/1908.feature similarity index 100% rename from changelogs/client_server/newsfragments/1903.feature rename to changelogs/client_server/newsfragments/1908.feature From 0580f5120693e2535920f5e57e4218e9467b7d18 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 May 2019 12:49:50 -0600 Subject: [PATCH 6/9] Clarify that failing to follow the flows == 401 --- specification/client_server_api.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 4b7065b3..3ea1411e 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -407,8 +407,9 @@ an additional stage. This exchange continues until the final success. For each endpoint, a server offers one or more 'flows' that the client can use to authenticate itself. Each flow comprises a series of stages, as described above. The client is free to choose which flow it follows, however the flow's -stages must be completed in order. When all stages in a flow are complete, -authentication is complete and the API call succeeds. +stages must be completed in order. Failing to follow the flows in order must +result in an HTTP 401 response, as defined below. When all stages in a flow +are complete, authentication is complete and the API call succeeds. User-interactive API in the REST API <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< From 15b8011f63a687bc8961c881c1dcb73fd4318c6b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 13:37:58 -0600 Subject: [PATCH 7/9] Add missing aesthetic parameters to /store-invite Fixes https://github.com/matrix-org/matrix-doc/issues/2048 --- api/identity/store_invite.yaml | 47 ++++++++++++++++--- .../newsfragments/2049.clarification | 1 + 2 files changed, 42 insertions(+), 6 deletions(-) create mode 100644 changelogs/identity_service/newsfragments/2049.clarification diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index 69103294..bca78d7e 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -50,31 +50,66 @@ paths: requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``. Currently, invites may only be issued for 3pids of the ``email`` medium. + + Optional fields in the request should be populated to the best of the + server's ability. Identity servers may use these variables when notifying + the ``address`` of the pending invite for display purposes. operationId: storeInvite parameters: - in: body name: body schema: type: object - example: { - "medium": "email", - "address": "foo@bar.baz", - "room_id": "!something:example.tld", - "sender": "@bob:example.com" - } properties: medium: type: string description: The literal string ``email``. + example: "email" address: type: string description: The email address of the invited user. + example: "foo@example.com" room_id: type: string description: The Matrix room ID to which the user is invited + example: "!something:example.org" sender: type: string description: The Matrix user ID of the inviting user + example: "@bob:example.com" + room_alias: + type: string + description: |- + The Matrix room alias for the room to which the user is + invited. This should be retrieved from the ``m.room.canonical_alias`` + state event. + example: "#somewhere:exmaple.org" + room_avatar_url: + type: string + description: |- + The Content URI for the room to which the user is invited. This should + be retrieved from the ``m.room.avatar`` state event. + example: "mxc://example.org/s0meM3dia" + room_join_rules: + type: string + description: |- + The ``join_rule`` for the room to which the user is invited. This should + be retrieved from the ``m.room.join_rules`` state event. + example: "public" + room_name: + type: string + description: |- + The name of the room to which the user is invited. This should be retrieved + from the ``m.room.name`` state event. + example: "Bob's Emporium of Messages" + sender_display_name: + type: string + description: The display name of the user ID initiating the invite. + example: "Bob Smith" + sender_avatar_url: + type: string + description: The Content URI for the avatar of the user ID initiating the invite. + example: "mxc://example.org/an0th3rM3dia" required: ["medium", "address", "room_id", "sender"] responses: 200: diff --git a/changelogs/identity_service/newsfragments/2049.clarification b/changelogs/identity_service/newsfragments/2049.clarification new file mode 100644 index 00000000..403ac8d0 --- /dev/null +++ b/changelogs/identity_service/newsfragments/2049.clarification @@ -0,0 +1 @@ +Add missing aesthetic parameters to ``/store-invite``. From 78d93432f4cf3fde1cb11af37b95fe16b46bbe0c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 14:00:34 -0600 Subject: [PATCH 8/9] Synchronize proposals_intro.rst and CONTRIBUTING.rst --- CONTRIBUTING.rst | 28 +++++++++++++++------------- specification/proposals_intro.rst | 26 +++++++++++++++++--------- 2 files changed, 32 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7a6c6be2..0b814fb9 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -26,10 +26,11 @@ For this to be effective, the APIs need to be present and working correctly in a server before they can be documented in the specification. This process can take some time to complete. -For this reason, we have not found the github pull-request model effective for -discussing changes to the specification. Instead, we have adopted the workflow -as described at https://matrix.org/docs/spec/proposals - *please read this for -details on how to contribute spec changes*. +Changes to the protocol (new endpoints, ideas, etc) need to go through the +`proposals process `_. Other changes, +such as fixing bugs, typos, or clarifying existing behaviour do not need a proposal. +If you're not sure, visit us at `#matrix-spec:matrix.org`_ +and ask. Other changes @@ -51,8 +52,7 @@ following: `_ label. (If there is any doubt about whether it is the spec or the implementations - that need fixing, please discuss it with us first in `#matrix-dev:matrix.org - `_.) + that need fixing, please discuss it with us first in `#matrix-spec:matrix.org`_.) * Clarifications to the specification which do not change the behaviour of Matrix servers or clients in a way which might introduce compatibility @@ -60,14 +60,16 @@ following: `clarification `_ label. - For example, recommendations for UI behaviour do not require a proposal - document. On the other hand, changes to event contents would be best - discussed in a proposal document even though no changes would be necessary to - server implementations. + For example, areas where the specification is unclear do not require a proposal + to fix. On the other hand, introducing new behaviour is best represented by a + proposal. -For such changes, please do just open a `pull request`_. +For such changes, please do just open a `pull request`_. If you're not sure if +your change is covered by the above, please visit `#matrix-spec:matrix.org` and +ask. -.. _pull request: https://help.github.com/articles/about-pull-requests +.. _`pull request`: https://help.github.com/articles/about-pull-requests +.. _`#matrix-spec:matrix.org`: https://matrix.to/#/#matrix-spec:matrix.org Adding to the changelog @@ -96,7 +98,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following: * ``breaking`` - Used when the change is not backwards compatible. -* ``deprecation`` - Used when deprecating something +* ``deprecation`` - Used when deprecating something. All news fragments must have a brief summary explaining the change in the contents of the file. The summary must end in a full stop to be in line with diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index d95128b7..d492700e 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -13,12 +13,18 @@ Proposals for Spec Changes to Matrix If you are interested in submitting a change to the Matrix Specification, please take note of the following guidelines. -All changes to Specification content require a formal proposal process. This -involves writing a proposal, having it reviewed by everyone, having the -proposal being accepted, then actually having your ideas implemented as -committed changes to the `Specification repository +Most changes to the Specification require a formal proposal. Bug fixes, typos, +and clarifications to existing behaviour do not need proposals - see the +`contributing guide `_ +for more information on what does and does not need a proposal. + +The proposal process involves some technical writing, having it reviewed by +everyone, having the proposal being accepted, then actually having your ideas +implemented as committed changes to the `Specification repository `_. +.. TODO: Replace GH team link with https://matrix.org/foundation or something + Meet the `members of the Core Team `_, a group of individuals tasked with ensuring the spec process is as smooth and painless as @@ -33,14 +39,15 @@ Guiding Principles Proposals **must** act to the greater benefit of the entire Matrix ecosystem, rather than benefiting or privileging any single player or subset of players - -and must not contain any patent encumbered intellectual property. Members of the Core Team pledge to act as -a neutral custodian for Matrix on behalf of the whole ecosystem. +and must not contain any patent encumbered intellectual property. Members of +the Core Team pledge to act as a neutral custodian for Matrix on behalf of the +whole ecosystem. For clarity: the Matrix ecosystem is anyone who uses the Matrix protocol. That includes client users, server admins, client developers, bot developers, -bridge and application service developers, users and admins who are indirectly using Matrix via -3rd party networks which happen to be bridged, server developers, room -moderators and admins, companies/projects building products or services on +bridge and application service developers, users and admins who are indirectly +using Matrix via 3rd party networks which happen to be bridged, server developers, +room moderators and admins, companies/projects building products or services on Matrix, spec contributors, translators, and those who created it in the first place. @@ -242,6 +249,7 @@ Spec PR Merged merged A proposal with Postponed proposal-postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps sometime in the future Closed proposal-closed A proposal which has been reviewed and deemed unsuitable for acceptance +Obsolete obsolete A proposal which has been made obsolete by another proposal or decision elsewhere. =============================== ============================= ==================================== From 464845feb0695c99f1b81e665e980e0289ec119c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 16:36:43 -0600 Subject: [PATCH 9/9] Make url required for m.file-like messages Fixes https://github.com/matrix-org/matrix-doc/issues/2008 This also removes `filename` from `m.file` because it has never been used in practice. --- changelogs/client_server/newsfragments/2053.clarification | 1 + event-schemas/schema/m.room.message#m.audio | 1 + event-schemas/schema/m.room.message#m.file | 2 +- event-schemas/schema/m.room.message#m.image | 1 + event-schemas/schema/m.room.message#m.video | 1 + 5 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2053.clarification diff --git a/changelogs/client_server/newsfragments/2053.clarification b/changelogs/client_server/newsfragments/2053.clarification new file mode 100644 index 00000000..2a72a88e --- /dev/null +++ b/changelogs/client_server/newsfragments/2053.clarification @@ -0,0 +1 @@ +Clarify the required fields on ``m.file`` (and similar) messages. diff --git a/event-schemas/schema/m.room.message#m.audio b/event-schemas/schema/m.room.message#m.audio index c258b85f..99e28110 100644 --- a/event-schemas/schema/m.room.message#m.audio +++ b/event-schemas/schema/m.room.message#m.audio @@ -38,6 +38,7 @@ properties: required: - msgtype - body + - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message#m.file b/event-schemas/schema/m.room.message#m.file index 2fb4fe50..2389d8a9 100644 --- a/event-schemas/schema/m.room.message#m.file +++ b/event-schemas/schema/m.room.message#m.file @@ -53,7 +53,7 @@ properties: required: - msgtype - body - - filename + - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message#m.image b/event-schemas/schema/m.room.message#m.image index 349f78f4..1e6ebeaa 100644 --- a/event-schemas/schema/m.room.message#m.image +++ b/event-schemas/schema/m.room.message#m.image @@ -28,6 +28,7 @@ properties: required: - msgtype - body + - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message#m.video b/event-schemas/schema/m.room.message#m.video index 8a66fdeb..2da7e0bc 100644 --- a/event-schemas/schema/m.room.message#m.video +++ b/event-schemas/schema/m.room.message#m.video @@ -59,6 +59,7 @@ properties: required: - msgtype - body + - url type: object type: enum: