Merge branch 'master' into travis/1.0/fix-examples

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 <https://matrix.org/docs/spec/proposals>`_. 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:
   <https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_ 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
-  <http://matrix.to/#/#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 <https://github.com/matrix-org/matrix-doc/labels/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

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:

changelogs/client_server/newsfragments/2036.clarification

@@ -0,0 +1 @@
+Clarify that ``FAIL_ERROR`` in autodiscovery is not limited to just homeservers.

changelogs/client_server/newsfragments/2042.clarification

@@ -0,0 +1 @@
+Clarify that login flows are meant to be completed in order.

changelogs/client_server/newsfragments/2053.clarification

@@ -0,0 +1 @@
+Clarify the required fields on ``m.file`` (and similar) messages.

changelogs/identity_service/newsfragments/2049.clarification

@@ -0,0 +1 @@
+Add missing aesthetic parameters to ``/store-invite``.

changelogs/server_server/newsfragments/1904.clarification

@@ -1 +0,0 @@
-Fix the `access_token` parameter in the open_id endpoint.

changelogs/server_server/newsfragments/1906.clarification

@@ -0,0 +1 @@
+Fix the ``access_token`` parameter in the open_id endpoint.

event-schemas/schema/m.room.message$m.audio

@@ -38,6 +38,7 @@ properties:
     required:
       - msgtype
       - body
+      - url
     type: object
   type:
     enum:

event-schemas/schema/m.room.message$m.file

@@ -53,7 +53,7 @@ properties:
     required:
       - msgtype
       - body
-      - filename
+      - url
     type: object
   type:
     enum:

event-schemas/schema/m.room.message$m.image

@@ -28,6 +28,7 @@ properties:
     required:
       - msgtype
       - body
+      - url
     type: object
   type:
     enum:

event-schemas/schema/m.room.message$m.video

@@ -59,6 +59,7 @@ properties:
     required:
       - msgtype
       - body
+      - url
     type: object
   type:
     enum:

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.
 
@@ -406,8 +406,10 @@ 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. 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
 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

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 <https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst>`_
+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
 <https://github.com/matrix-org/matrix-doc>`_.
 
+.. TODO: Replace GH team link with https://matrix.org/foundation or something
+
 Meet the `members of the Core Team
 <https://github.com/orgs/matrix-org/teams/spec-core-team/members>`_, 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.
 ===============================  =============================  ====================================