Add intro and further details to server-side changes

proposals/3765-rich-room-topics.md

@@ -44,34 +44,52 @@ 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
 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
 
 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