Merge branch 'master' into travis/clarification/lowercasing

Author: turt2live

changelogs/client_server/newsfragments/2985.clarification

@@ -0,0 +1 @@
+Correct examples of `client_secret` request body parameters so that they do not include invalid characters.

changelogs/identity_service/newsfragments/3170.removal

@@ -0,0 +1 @@
+The v1 identity service API has been removed in favour of the v2 API, as per [MSC2713](https://github.com/matrix-org/matrix-doc/pull/2713).

content/appendices.md

@@ -590,32 +590,6 @@ Event IDs and Room IDs are case-sensitive. They are not meant to be
 human-readable. They are intended to be treated as fully opaque strings
 by clients.
 
-#### Group Identifiers
-
-Groups within Matrix are uniquely identified by their group ID. The
-group ID is namespaced to the group server which hosts this group and
-has the form:
-
-    +localpart:domain
-
-The `localpart` of a group ID is an opaque identifier for that group. It
-MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`,
-`.`, `_`, `=`, `-`, and `/`.
-
-The `domain` of a group ID is the [server name](#server-name) of the
-group server which hosts this group.
-
-The length of a group ID, including the `+` sigil and the domain, MUST
-NOT exceed 255 characters.
-
-The complete grammar for a legal group ID is:
-
-    group_id = "+" group_id_localpart ":" server_name
-    group_id_localpart = 1*group_id_char
-    group_id_char = DIGIT
-                 / %x61-7A                   ; a-z
-                 / "-" / "." / "=" / "_" / "/"
-
 #### Room Aliases
 
 A room may have zero or more aliases. A room alias has the format:
@@ -674,7 +648,6 @@ Examples of matrix.to URIs are:
 -   Permalink by room alias:
     `https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org`
 -   User: `https://matrix.to/#/%40alice%3Aexample.org`
--   Group: `https://matrix.to/#/%2Bexample%3Aexample.org`
 
 {{% boxes/note %}}
 Historically, clients have not produced URIs which are fully encoded.
@@ -690,6 +663,16 @@ versions](/#room-versions). These slashes should normally be
 encoded when producing matrix.to URIs, however.
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+<!-- TODO: @@TravisR: Make "Spaces" a link when that specification exists -->
+In prior versions of this specification, a concept of "groups" were mentioned
+to organize rooms. This functionality did not properly get introduced into
+the specification and is subsequently replaced with "Spaces". Historical
+matrix.to URIs pointing to groups might still exist: they take the form
+`https://matrix.to/#/%2Bexample%3Aexample.org` (where the `+` sigil may or
+may not be encoded).
+{{% /boxes/note %}}
+
 ##### Routing
 
 Room IDs are not routable on their own as there is no reliable domain to

content/client-server-api/_index.md

@@ -297,7 +297,7 @@ specify parameter values. The flow for this method is as follows:
     6.  If the `m.identity_server` property is present, extract the
         `base_url` value for use as the base URL of the identity server.
         Validation for this URL is done as in the step above, but using
-        `/_matrix/identity/api/v1` as the endpoint to connect to. If the
+        `/_matrix/identity/v2` as the endpoint to connect to. If the
         `m.identity_server` property is present, but does not have a
         `base_url` value, then `FAIL_PROMPT`.
 

content/identity-service-api.md

@@ -59,48 +59,48 @@ the keys `error` and `errcode` MUST always be present.
 
 Some standard error codes are below:
 
-`M_NOT_FOUND`  
+`M_NOT_FOUND`
 The resource requested could not be located.
 
-`M_MISSING_PARAMS`  
+`M_MISSING_PARAMS`
 The request was missing one or more parameters.
 
-`M_INVALID_PARAM`  
+`M_INVALID_PARAM`
 The request contained one or more invalid parameters.
 
-`M_SESSION_NOT_VALIDATED`  
+`M_SESSION_NOT_VALIDATED`
 The session has not been validated.
 
-`M_NO_VALID_SESSION`  
+`M_NO_VALID_SESSION`
 A session could not be located for the given parameters.
 
-`M_SESSION_EXPIRED`  
+`M_SESSION_EXPIRED`
 The session has expired and must be renewed.
 
-`M_INVALID_EMAIL`  
+`M_INVALID_EMAIL`
 The email address provided was not valid.
 
-`M_EMAIL_SEND_ERROR`  
+`M_EMAIL_SEND_ERROR`
 There was an error sending an email. Typically seen when attempting to
 verify ownership of a given email address.
 
-`M_INVALID_ADDRESS`  
+`M_INVALID_ADDRESS`
 The provided third party address was not valid.
 
-`M_SEND_ERROR`  
+`M_SEND_ERROR`
 There was an error sending a notification. Typically seen when
 attempting to verify ownership of a given third party address.
 
-`M_UNRECOGNIZED`  
+`M_UNRECOGNIZED`
 The request contained an unrecognised value, such as an unknown token or
 medium.
 
-`M_THREEPID_IN_USE`  
+`M_THREEPID_IN_USE`
 The third party identifier is already in use by another user. Typically
 this error will have an additional `mxid` property to indicate who owns
 the third party identifier.
 
-`M_UNKNOWN`  
+`M_UNKNOWN`
 An unknown error has occurred.
 
 {{% http-api spec="identity" api="versions" %}}
@@ -116,22 +116,6 @@ Matrix user identity, but not in the other direction (i.e. one should
 not be able to get all 3PIDs associated with a Matrix user ID, or get
 all 3PIDs associated with a 3PID).
 
-## Version 1 API deprecation
-
-As described on each of the version 1 endpoints, the v1 API is
-deprecated in favour of the v2 API described here. The major difference,
-with the exception of a few isolated cases, is that the v2 API requires
-authentication to ensure the user has given permission for the identity
-server to operate on their data.
-
-The v1 API is planned to be removed from the specification in a future
-version.
-
-Clients SHOULD attempt the v2 endpoints first, and if they receive a
-`404`, `400`, or similar error they should try the v1 endpoint or fail
-the operation. Clients are strongly encouraged to warn the user of the
-risks in using the v1 API, if they are planning on using it.
-
 ## Web browser clients
 
 It is realistic to expect that some clients will be written to be run
@@ -149,12 +133,9 @@ recommended CORS headers to be returned by servers on all requests are:
 
 ## Authentication
 
-Most `v2` endpoints in the Identity Service API require authentication
+Most endpoints in the Identity Service API require authentication
 in order to ensure that the requesting user has accepted all relevant
-policies and is otherwise permitted to make the request. The `v1` API
-(currently deprecated) does not require this authentication, however
-using `v1` is strongly discouraged as it will be removed in a future
-release.
+policies and is otherwise permitted to make the request.
 
 Identity Servers use a scheme similar to the Client-Server API's concept
 of access tokens to authenticate users. The access tokens provided by an
@@ -204,8 +185,6 @@ has just accepted are appended to `m.accepted_terms`.
 
 ## Status check
 
-{{% http-api spec="identity" api="ping" %}}
-
 {{% http-api spec="identity" api="v2_ping" %}}
 
 ## Key management
@@ -219,23 +198,14 @@ The identity server may also keep track of some short-term
 public-private keypairs, which may have different usage and lifetime
 characteristics than the service's long-term keys.
 
-{{% http-api spec="identity" api="pubkey" %}}
-
 {{% http-api spec="identity" api="v2_pubkey" %}}
 
 ## Association lookup
 
-{{% http-api spec="identity" api="lookup" %}}
-
 {{% http-api spec="identity" api="v2_lookup" %}}
 
 ### Client behaviour
 
-{{% boxes/note %}}
-This section only covers the v2 lookup endpoint. The v1 endpoint is
-described in isolation above.
-{{% /boxes/note %}}
-
 Prior to performing a lookup clients SHOULD make a request to the
 `/hash_details` endpoint to determine what algorithms the server
 supports (described in more detail below). The client then uses this
@@ -246,11 +216,6 @@ Clients MUST support at least the `sha256` algorithm.
 
 ### Server behaviour
 
-{{% boxes/note %}}
-This section only covers the v2 lookup endpoint. The v1 endpoint is
-described in isolation above.
-{{% /boxes/note %}}
-
 Servers, upon receipt of a `/lookup` request, will compare the query
 against known bindings it has, hashing the identifiers it knows about as
 needed to verify exact matches to the request.
@@ -400,20 +365,14 @@ through without modification.
 
 ### Email associations
 
-{{% http-api spec="identity" api="email_associations" %}}
-
 {{% http-api spec="identity" api="v2_email_associations" %}}
 
 ### Phone number associations
 
-{{% http-api spec="identity" api="phone_associations" %}}
-
 {{% http-api spec="identity" api="v2_phone_associations" %}}
 
 ### General
 
-{{% http-api spec="identity" api="associations" %}}
-
 {{% http-api spec="identity" api="v2_associations" %}}
 
 ## Invitation storage
@@ -429,8 +388,6 @@ the Matrix user's homeserver via the
 endpoint. The request MUST be signed with a long-term private key for
 the identity server.
 
-{{% http-api spec="identity" api="store_invite" %}}
-
 {{% http-api spec="identity" api="v2_store_invite" %}}
 
 ## Ephemeral invitation signing
@@ -440,6 +397,4 @@ identity server offers some crypto functionality to help in accepting
 invitations. This is less secure than the client doing it itself, but
 may be useful where this isn't possible.
 
-{{% http-api spec="identity" api="invitation_signing" %}}
-
 {{% http-api spec="identity" api="v2_invitation_signing" %}}

content/proposals.md

@@ -245,10 +245,13 @@ is as follows:
     75% of the members of the Spec Core Team agree on its outcome, and
     all existing concerns have been resolved.
 -   The FCP will then begin and last for 5 days, giving anyone else some
-    time to speak up before it concludes. On its conclusion, the
-    disposition of the FCP will be carried out. If sufficient reasoning
-    against the disposition is raised, the FCP can be cancelled and the
-    MSC will continue to evolve accordingly.
+    time to speak up before it concludes. If sufficient reasoning
+    against the disposition is provided, a member of the Spec Core Team can
+    raise a concern and block FCP from completing. This will not reset or
+    pause the 5 day FCP timer, but FCP will not conclude until all concerns have
+    been resolved. If sufficient change in the MSC is required to resolve those
+    concerns, FCP might be cancelled and reproposed. Once FCP has concluded,
+    the disposition of the FCP will be carried out.
 -   Once the proposal has been accepted and merged, it is time to submit
     the actual change to the Specification that your proposal reasoned
     about. This is known as a spec PR. However in order for the spec PR
@@ -259,7 +262,7 @@ is as follows:
     will warrant another MSC. Any minor, non-fundamental changes are
     allowed but **must** be documented in the original proposal
     document. This ensures that someone reading a proposal in the future
-    doesn't assume old information wasn't merged into the spec.
+    doesn't assume old information that wasn't merged into the spec.
     -   Similar to the proposal PR, please sign off the spec PR as per
         the guidelines on
         [CONTRIBUTING.rst](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst).
@@ -373,7 +376,7 @@ be merged without the Spec Core Team focusing on them specifically.
 
 ## Implementing a proposal
 
-As part of the proposal process the spec core team will require evidence
+As part of the proposal process the Spec Core Team will require evidence
 of the MSC working in order for it to move into FCP. This can usually be
 a branch/pull request to whichever implementation of choice that proves
 the MSC works in practice, though in some cases the MSC itself will be
@@ -388,13 +391,11 @@ release, implementations are required to use the following process to
 ensure that the official Matrix namespace is not cluttered with
 development or testing data.
 
-Note
-
-Unreleased implementations (including proofs-of-concept demonstrating
+**Note:** Unreleased implementations (including proofs-of-concept demonstrating
 that a particular MSC works) do not have to follow this process.
 
 1.  Have an idea for a feature.
-2.  Implement the feature using unstable endpoints, vendor prefixes, and
+1.  Implement the feature using unstable endpoints, vendor prefixes, and
     unstable feature flags as appropriate.
     -   When using unstable endpoints, they MUST include a vendor
         prefix. For example:
@@ -429,22 +430,25 @@ that a particular MSC works) do not have to follow this process.
     -   If at any point after early release, the idea changes in a
         backwards-incompatible way, the feature flag should also change
         so that implementations can adapt as needed.
-3.  In parallel, or ahead of implementation, open an MSC and solicit
+1.  In parallel, or ahead of implementation, open an MSC and solicit
     review per above.
-4.  Before FCP can be called, the Spec Core Team will require evidence
+1.  Before FCP can be called, the Spec Core Team will require evidence
     of the MSC working as proposed. A typical example of this is an
     implementation of the MSC, though the implementation does not need
     to be shipped anywhere and can therefore avoid the
     forwards/backwards compatibility concerns mentioned here.
-5.  The FCP process is completed, and assuming nothing is flagged the
+1.  The FCP process is completed, and assuming nothing is flagged the
     MSC lands.
-6.  A spec PR is written to incorporate the changes into Matrix.
-7.  A spec release happens.
-8.  Implementations switch to using stable prefixes (e.g.: `/r0`) if the
-    server supports the specification version released. If the server
-    doesn't advertise the specification version, but does have the
-    feature flag, unstable prefixes should still be used.
-9.  A transition period of about 2 months starts immediately after the
+1.  Implementations can now switch to using stable prefixes
+    (for example, for an endpoint, moving from
+    `/unstable/org.matrix.mscxxxx/frobnicate`
+    to `/v1/frobnicate`), assuming that the change
+    is backwards compatible with older implementations. In the rare occasion
+    where backwards compatibility is not possible without a new spec release,
+    implementations should continue to use unstable prefixes.
+1.  A spec PR is written to incorporate the changes into Matrix.
+1.  A spec release happens.
+1.  A transition period of about 2 months starts immediately after the
     spec release, before implementations start to encourage other
     implementations to switch to stable endpoints. For example, a server
     implementation should start asking client implementations to support
@@ -463,9 +467,9 @@ com.example/new/endpoint`.
 
 In summary:
 
--   Implementations MUST NOT use stable endpoints before the MSC is in
-    the spec. This includes NOT using stable endpoints in the period
-    between completion of FCP and release of the spec. passed.
+-   Implementations MUST NOT use stable endpoints before the MSC has
+    completed FCP. Once that has occurred, implementations are allowed
+    to use stable endpoints, but are not required to.
 -   Implementations are able to ship features that are exposed to users
     by default before an MSC has been merged to the spec, provided they
     follow the process above.