From ab7b646f4157acb9cd6adc6e212a0f45532c839f Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 17 Oct 2024 09:55:18 +0200 Subject: [PATCH] Add intro and further details to server-side changes --- proposals/3765-rich-room-topics.md | 53 +++++++++++++++++++++--------- 1 file changed, 38 insertions(+), 15 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 15ec039d85e..8b096924592 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -44,6 +44,10 @@ The wrapping `m.topic` content block is similar to `m.caption` for file uploads as defined in [MSC3551]. It avoids clients accidentally rendering the topic state event as a room message. +It is recommended that clients always include a plain text variant when +sending `m.topic` events. This prevents bad UX in situations where a plain +text topic is sufficient such as the public rooms directory. + In order to prevent formatting abuse in room topics, clients are encouraged to limit the length of topics to at most two lines. Additionally, clients should ignore things like headings and enumerations (or format them @@ -51,20 +55,30 @@ as regular text). A future MSC may introduce a mechanism to capture extended multiline details that are not suitable for room topics in a separate field or event type. -A change to [`/_matrix/client/v3/createRoom`] is not necessary. The -endpoint has a plain text `topic` parameter but also allows to specify a -full `m.topic` event in `initial_state`. - -Room topics also occur as part of the `PublicRoomsChunk` object in the -responses of [`/_matrix/client/v3/publicRooms`] and -[`/_matrix/client/v1/rooms/{roomId}/hierarchy`]. The topic can be kept -plain text here because this data should commonly only be displayed to -users that are *not* a member of the room yet. These users will not have -the same need for rich room topics as users who are inside the room. If -no plain text topic exists, home servers should return an empty topic -string from these end points. Since this will inevitably lead to bad UX, -client implementations are encouraged to always include a plain text -variant when sending `m.topic` events. +On the server side, any logic that currently operates on `m.room.topic` is +updated to use `m.topic` instead. + +In [`/_matrix/client/v3/createRoom`], the `topic` parameter causes `m.topic` +to be written with a `text/plain` mimetype. If an `m.topic` event is supplied +in `initial_state`, the `topic` parameter overwrites its `text/plain` mimetype +but retains any other mimetypes. + +In [`GET /_matrix/client/v3/publicRooms`], [`GET /_matrix/federation/v1/publicRooms`] +and their `POST` siblings, the `topic` response field is read from the +`text/plain` mimetype of `m.topic` if it exists or omitted otherwise. +A plain text topic is sufficient here because this data is commonly +only displayed to users that are *not* a member of the room yet. These +users don't have the same need for rich room topics as users who already +reside in the room. + +The same logic is applied to [`/_matrix/client/v1/rooms/{roomId}/hierarchy`] +and [`/_matrix/federation/v1/hierarchy/{roomId}`]. + +In [server side search], the `room_events` category is expanded to search +over the `text/plain` mimetype in `m.topic`. + +Finally, `m.topic` is also added to the events that are recommended for +inclusion in [stripped state]. ## Transition @@ -72,6 +86,10 @@ As this MSC replaces `m.room.topic` for an extensible alternative, clients and servers are expected to treat `m.room.topic` as invalid in extensible event-supporting room versions. +It is recommended that servers replicate `m.room.topic` to `m.topic` +with a plain text mimetype and vice versa when [upgrading] between room +versions that do and don't support extensible events. + ## Potential issues None. @@ -101,6 +119,11 @@ as `org.matrix.msc3765.topic`. [plain text]: https://spec.matrix.org/v1.12/client-server-api/#mroomtopic [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 +[server side search]: https://spec.matrix.org/v1.12/client-server-api/#server-side-search +[stripped state]: https://spec.matrix.org/v1.12/client-server-api/#stripped-state +[upgrading]: https://spec.matrix.org/v1.12/client-server-api/#room-upgrades [`/_matrix/client/v1/rooms/{roomId}/hierarchy`]: https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv1roomsroomidhierarchy [`/_matrix/client/v3/createRoom`]: https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3createroom -[`/_matrix/client/v3/publicRooms`]: https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv3publicrooms +[`/_matrix/federation/v1/hierarchy/{roomId}`]: https://spec.matrix.org/v1.12/server-server-api/#get_matrixfederationv1hierarchyroomid +[`GET /_matrix/client/v3/publicRooms`]: https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv3publicrooms +[`GET /_matrix/federation/v1/publicRooms`]: https://spec.matrix.org/v1.12/server-server-api/#get_matrixfederationv1publicrooms