wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source
This commit is contained in:
Travis Ralston 2019-05-30 16:57:51 -06:00
commit d7f37f92eb
15 changed files with 87 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

28
CONTRIBUTING.rst
View file

@ -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

47
api/identity/store_invite.yaml
View file

@ -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:

0
changelogs/client_server/newsfragments/1903.feature → changelogs/client_server/newsfragments/1908.feature
View file

1
changelogs/client_server/newsfragments/2036.clarification Normal file
View file

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

1
changelogs/client_server/newsfragments/2042.clarification Normal file
View file

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

1
changelogs/client_server/newsfragments/2053.clarification Normal file
View file

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

1
changelogs/identity_service/newsfragments/2049.clarification Normal file
View file

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

1
changelogs/server_server/newsfragments/1904.clarification
View file

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

1
changelogs/server_server/newsfragments/1906.clarification Normal file
View file

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

1
event-schemas/schema/m.room.message$m.audio
View file

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

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

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

1
event-schemas/schema/m.room.message$m.image
View file

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

1
event-schemas/schema/m.room.message$m.video
View file

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

8
specification/client_server_api.rst
View file

@ -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
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

26
specification/proposals_intro.rst
View file

@ -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.
=============================== ============================= ====================================