From 29745d04fb669ce2b23c470ca68f164eb05590f6 Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Tue, 26 Nov 2019 11:19:57 +0000
Subject: [PATCH] erikj/msc_membership_reasons

---
 proposals/2367-membership-reasons.md | 77 ++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 proposals/2367-membership-reasons.md

diff --git a/proposals/2367-membership-reasons.md b/proposals/2367-membership-reasons.md
new file mode 100644
index 00000000000..479fce345b5
--- /dev/null
+++ b/proposals/2367-membership-reasons.md
@@ -0,0 +1,77 @@
+# 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}
+```
+
+If specified the `reason` field will be added to the generated membership
+event's content.
+
+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.