commit
6005c16b60
@ -0,0 +1,2 @@
|
|||||||
|
patreon: matrixdotorg
|
||||||
|
liberapay: matrixdotorg
|
@ -0,0 +1,19 @@
|
|||||||
|
---
|
||||||
|
name: Proposal ready for review
|
||||||
|
about: A proposal that is ready for review by the core team and community.
|
||||||
|
title: ''
|
||||||
|
labels: proposal, proposal-in-review
|
||||||
|
assignees: ''
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- Put your "rendered" link here -->
|
||||||
|
|
||||||
|
### Pull Request Checklist
|
||||||
|
|
||||||
|
<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
|
||||||
|
|
||||||
|
* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
|
||||||
|
* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
|
||||||
|
* [ ] Pull request includes ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
|
||||||
|
* [ ] Pull request title and file name include this PR's number as the MSC number.
|
@ -0,0 +1,16 @@
|
|||||||
|
---
|
||||||
|
name: Spec clarification/not a proposal
|
||||||
|
about: A change that's not a spec proposal, such as a clarification to the spec itself.
|
||||||
|
title: ''
|
||||||
|
labels: ''
|
||||||
|
assignees: ''
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Pull Request Checklist
|
||||||
|
|
||||||
|
<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
|
||||||
|
|
||||||
|
* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
|
||||||
|
* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
|
||||||
|
* [ ] Pull request is classified as ['other changes'](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#other-changes)
|
@ -0,0 +1,20 @@
|
|||||||
|
---
|
||||||
|
name: WIP Proposal
|
||||||
|
about: A proposal that isn't quite ready for formal review yet.
|
||||||
|
title: '[WIP] Your Proposal Title'
|
||||||
|
labels: proposal
|
||||||
|
assignees: ''
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- Put your "rendered" link here -->
|
||||||
|
|
||||||
|
### Pull Request Checklist
|
||||||
|
|
||||||
|
<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
|
||||||
|
|
||||||
|
* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
|
||||||
|
* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
|
||||||
|
* [ ] A ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
|
||||||
|
* [ ] Update the title and file name of your proposal to match this PR's number (after opening).
|
||||||
|
* [ ] Ask in [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) to get this marked as ready for review, once it is ready for review.
|
@ -0,0 +1 @@
|
|||||||
|
Minor clarifications to token-based User-Interactive Authentication.
|
@ -0,0 +1 @@
|
|||||||
|
Minor clarification for what the user directory searches.
|
@ -0,0 +1,124 @@
|
|||||||
|
# MSC2324: Facilitating early releases of software dependent on spec
|
||||||
|
|
||||||
|
*Note*: This is a process change MSC, not a change to the spec itself.
|
||||||
|
|
||||||
|
There's currently an unanswered question by the spec process: when is it
|
||||||
|
safe to start using stable endpoints or to present a feature as "stable"?
|
||||||
|
Historically this question would receive very different answers depending
|
||||||
|
on who you asked, so in an effort to come up with a concise answer the
|
||||||
|
following process change is proposed.
|
||||||
|
|
||||||
|
## Proposal
|
||||||
|
|
||||||
|
The new process, from start to finish, is proposed as:
|
||||||
|
|
||||||
|
1. Have an idea for a feature.
|
||||||
|
2. Optionally: 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: `/_matrix/client/unstable/com.example/login`. Vendor prefixes
|
||||||
|
throughout this proposal always use the Java package naming convention.
|
||||||
|
* Unstable endpoints **do not** inherit from stable (`/r0`) APIs. Previously,
|
||||||
|
one could access the entirety of the Matrix API through `/unstable` however
|
||||||
|
this is generally considered a bad practice. Therefore an implementation
|
||||||
|
can no longer assume that because its feature-specific endpoint exists that
|
||||||
|
any other endpoint will exist in the same unstable namespace.
|
||||||
|
* If the client needs to be sure the server supports the feature, an unstable
|
||||||
|
feature flag that MUST be vendor prefixed is to be used. This kind of flag
|
||||||
|
shows up in the `unstable_features` field of `/versions` as, for example,
|
||||||
|
`com.example.new_login`.
|
||||||
|
* You can ship the feature at *any* time, so long as you are able to accept
|
||||||
|
the technical debt that results from needing to provide adequate backwards
|
||||||
|
and forwards compatibility for the vendor prefixed implementation. The
|
||||||
|
implementation MUST support the flag disappearing and be generally safe for
|
||||||
|
users. Note that implementations early in the MSC review process may also be
|
||||||
|
required to provide backwards compatibility with earlier editions of the
|
||||||
|
proposal.
|
||||||
|
* If you don't want to support the technical debt (or if it's impossible to
|
||||||
|
provide adequate backwards/forwards compatibility - e.g. a user authentication
|
||||||
|
change which can't be safely rolled back), do not implement the feature and
|
||||||
|
wait for Step 7.
|
||||||
|
* If at any point the idea changes, 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 review.
|
||||||
|
4. Before a FCP (Final Comment Period) can be called, the Spec Core Team will
|
||||||
|
require that evidence to prove the MSC works be presented. A typical example
|
||||||
|
of this is an implementation of the MSC (which does not necessarily need to have been shipped anywhere).
|
||||||
|
5. FCP is gone through, 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 spec release, before
|
||||||
|
implementations start to loudly encourage other implementations to switch to stable
|
||||||
|
endpoints. For example, the Synapse team should start asking the Riot team to
|
||||||
|
support the stable endpoints (as per Step 8) 2 months after the spec release if they
|
||||||
|
haven't already.
|
||||||
|
|
||||||
|
It's worth repeating that this process generally only applies if the implementation
|
||||||
|
wants to ship the feature ahead of the spec being available. By doing so, it takes
|
||||||
|
on the risk that the spec/MSC may change and it must adapt. If the implementation
|
||||||
|
is unable to take on that risk, or simply doesn't mind waiting, it should go through
|
||||||
|
the spec process without shipping an unstable implementation.
|
||||||
|
|
||||||
|
To help MSCs get incorporated by implementations as stable features, the spec core
|
||||||
|
team plans to release the specification more often. How often is undefined and is
|
||||||
|
largely a case-by-case basis.
|
||||||
|
|
||||||
|
To reiterate:
|
||||||
|
|
||||||
|
* Implementations MUST NOT use stable endpoints before the MSC is in the spec. This
|
||||||
|
includes NOT using stable endpoints post-FCP.
|
||||||
|
* Implementations CAN ship features that are exposed by default to users before an
|
||||||
|
MSC has been merged to the spec, provided they follow the process above.
|
||||||
|
* Implementations SHOULD be wary of the technical debt they are incurring by moving
|
||||||
|
faster than the spec.
|
||||||
|
|
||||||
|
To clarify:
|
||||||
|
|
||||||
|
* The vendor prefix is chosen by the developer of the feature, using the Java package
|
||||||
|
naming convention. For example, `org.matrix` is the foundation's vendor prefix.
|
||||||
|
* The vendor prefixes, unstable feature flags, and unstable endpoints should be included
|
||||||
|
in the MSC so other developers can benefit. The MSC MUST still say what the stable
|
||||||
|
endpoints are to look like.
|
||||||
|
|
||||||
|
### Specific examples outside of the client-server API
|
||||||
|
|
||||||
|
There are some instances where a change might be made outside of the client-server API,
|
||||||
|
which is where much of this proposal is targetted. The general spirit of the process
|
||||||
|
should be followed where possible, if implementations decide to work ahead of spec releases.
|
||||||
|
|
||||||
|
#### Room versions
|
||||||
|
|
||||||
|
When a new room version is needed, implementations MUST use vendor-prefixed versions
|
||||||
|
before using the namespace reserved for Matrix (see https://matrix.org/docs/spec/#room-versions).
|
||||||
|
A room version is considered released once it is listed as an "available room version" in
|
||||||
|
the spec. Often a new room version is accompanied with a server-server API release, but
|
||||||
|
doesn't have to be.
|
||||||
|
|
||||||
|
#### Server-server / Identity / Push / Appservice API
|
||||||
|
|
||||||
|
These APIs don't yet have a `/versions` endpoint or similar. Typically behaviour changes in
|
||||||
|
these APIs are introduced with backwards compatibility in mind (try X and if that fails fall
|
||||||
|
back to Y) and therefore don't always need a flag to indicate support. If a flag were to
|
||||||
|
be required, an `unstable_features` or similar array would need to be exposed somewhere.
|
||||||
|
|
||||||
|
#### Changes to request/response parameters
|
||||||
|
|
||||||
|
Parameters being added to request/response bodies and query strings MUST be vendor-prefixed
|
||||||
|
per the proposed process. For example, a new JSON field might be `{"org.matrix.example": true}`
|
||||||
|
with the proposal being for `example` being added. A query string parameter would be prefixed
|
||||||
|
the same way: `?org.matrix.example=true`.
|
||||||
|
|
||||||
|
If the MSC is simply adding fields to already-versioned endpoints, it does not need to put
|
||||||
|
the whole endpoint into the `/unstable` namespace provided the new parameters are prefixed
|
||||||
|
appropriately.
|
||||||
|
|
||||||
|
#### .well-known and other APIs that can't be versioned
|
||||||
|
|
||||||
|
Best effort is appreciated. Typically these endpoints will be receiving minor behavioural
|
||||||
|
changes or new fields. New fields should be appropriately prefixed, and behaviour changes
|
||||||
|
should be rolled out cautiously by implementations (waiting until after FCP has concluded
|
||||||
|
is probably best to ensure there's no major problems with the new behaviour).
|
@ -0,0 +1,81 @@
|
|||||||
|
# Allowing Reasons in all Membership Events
|
||||||
|
|
||||||
|
Currently users can specify a reason for kicking or banning users in a room
|
||||||
|
that both the target and other users in a room can see. This is useful to
|
||||||
|
explain *why* an action without having to send separate messages.
|
||||||
|
|
||||||
|
The proposal extends this to all events, including invites, invite rejections
|
||||||
|
and leaves for similar reasons.
|
||||||
|
|
||||||
|
## Proposal
|
||||||
|
|
||||||
|
Allow `reason` field to be specified for all of the following APIs:
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /_matrix/client/r0/rooms/{roomId}/invite
|
||||||
|
POST /_matrix/client/r0/rooms/{roomId}/leave
|
||||||
|
POST /_matrix/client/r0/rooms/{roomId}/kick
|
||||||
|
POST /_matrix/client/r0/rooms/{roomId}/ban
|
||||||
|
POST /_matrix/client/r0/rooms/{roomId}/unban
|
||||||
|
POST /_matrix/client/r0/rooms/{roomId}/join
|
||||||
|
POST /_matrix/client/r0/join/{roomIdOrAlias}
|
||||||
|
PUT /_matrix/client/r0/rooms/{roomId}/state/m.room.member/{userID}
|
||||||
|
```
|
||||||
|
|
||||||
|
If specified the `reason` field will be added to the generated membership
|
||||||
|
event's content.
|
||||||
|
|
||||||
|
*Note: `/state/m.room.member` API currently allows this as clients can specify
|
||||||
|
arbitrary content already*
|
||||||
|
|
||||||
|
Clients may choose to display the reason for membership events in a room,
|
||||||
|
though may not do so if e.g. they have collapsed a set of membership changes.
|
||||||
|
|
||||||
|
Clients should not display an invite reason by default to the invitee as this
|
||||||
|
allows a classic abuse and harassment vector. However, clients may wish to show
|
||||||
|
invite reasons from known¹ senders, or have a button that allows viewing any
|
||||||
|
invite reason.
|
||||||
|
|
||||||
|
## Use Cases
|
||||||
|
|
||||||
|
Some basic use cases and examples are given below.
|
||||||
|
|
||||||
|
### Kick/ban
|
||||||
|
|
||||||
|
Kicking and banning already allow specifying a reason to allow giving a reason
|
||||||
|
for the moderation action (e.g. "Banned for spamming").
|
||||||
|
|
||||||
|
### Leaving a Room
|
||||||
|
|
||||||
|
A user may wish to leave a room e.g. because the room is no longer relevant
|
||||||
|
to them, allowing them to specify a reason means they can easily step out of
|
||||||
|
the room quietly without having to send a message to explain their actions.
|
||||||
|
|
||||||
|
### Invite
|
||||||
|
|
||||||
|
This can be useful to give some context for an invite, e.g. "Alice invites Bob
|
||||||
|
to get some feedback on the membership reasons MSC".
|
||||||
|
|
||||||
|
### Rejecting an Invite
|
||||||
|
|
||||||
|
If Alice has invited Bob (and many others) to a room to discuss going to a
|
||||||
|
concert then Bob may wish to simply reject the invite if he can't make it.
|
||||||
|
Adding a "will be out of town" reason to the rejection helps Alice to know why
|
||||||
|
her invite was rejected.
|
||||||
|
|
||||||
|
### Joining room
|
||||||
|
|
||||||
|
Adding a reason for joining could be used e.g. by automated bots to say why
|
||||||
|
they're joining. For example a bridge bot may join a room when asked to bridge
|
||||||
|
the room to an external network, in which case they may have a reason such as
|
||||||
|
"BridgeBot joined to bridge the room to RemoteNetwork at the request of Alice".
|
||||||
|
|
||||||
|
## Potential Issues
|
||||||
|
|
||||||
|
The main issue here is ensuring that the invite reason cannot be used as an
|
||||||
|
abuse vector, however if clients follow the recommendations above this concern
|
||||||
|
should be mitigated.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
¹ This is left up to implementations to decide, if they wish to do so.
|
Loading…
Reference in New Issue