Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MSC3765: Rich text in room topics #3765

Open
wants to merge 21 commits into
base: main
Choose a base branch
from
Open

MSC3765: Rich text in room topics #3765

Changes from 3 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
9b914c6
Add rich room topic MSC
Johennes Apr 3, 2022
06d315d
Rename to reflect propper MSC number
Johennes Apr 3, 2022
09c7014
Fix typo
Johennes Apr 3, 2022
1d0031a
Explain why m.topic is kept separate from m.message
Johennes Apr 4, 2022
3b572e7
Use json5 for formatting code snippet
Johennes Apr 4, 2022
6270109
Remove unneeded unstable room version
Johennes Apr 4, 2022
af184dd
Adapt to latest version of MSC1767
Johennes Jan 5, 2023
aa373d1
Add paragraph about preventing formatting abuse
Johennes Jan 5, 2023
ea93852
Introduce wrapping m.topic content block (#4111)
Johennes Feb 23, 2024
a6b1555
Clarify the case of HTML-only topics and transition logic (#4112)
Johennes Feb 23, 2024
95fb38a
Make it more explicit that m.topic replaces m.room.topic without depr…
Johennes Aug 26, 2024
f915cc4
Remove line-based formatting logic and limit length of topics (#4182)
Johennes Aug 27, 2024
385bf0b
Update MSC3765: Rich text in room topics (#4215)
Johennes Oct 17, 2024
bb726db
Accept suggestion
dbkr Oct 29, 2024
1b4682e
Clarify length / display limits.
clokep Nov 4, 2024
d42f0e3
Apply clarifications from author
clokep Nov 26, 2024
fda22d8
Make MSC3765 independent of extensible events and new room versions (…
Johennes Dec 12, 2024
ac5c6fc
Apply suggestions from code review
richvdh Dec 18, 2024
79e3f5d
Update proposals/3765-rich-room-topics.md
richvdh Jan 21, 2025
a64a825
Properly explain why the m.topic content block is needed (#4251)
Johennes Jan 21, 2025
c83f56d
Apply suggestions from code review
richvdh Jan 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 30 additions & 26 deletions proposals/3765-rich-room-topics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,10 +43,16 @@ repeated here.

The wrapping `m.topic` content block is similar to `m.caption` for file
uploads as defined in [MSC3551]. It avoids clients accidentally rendering
richvdh marked this conversation as resolved.
Show resolved Hide resolved
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
the topic as a room message. Note that while [MSC1767] had explicitly
excluded state events from being treated as extensible, this is being
changed with [MSC4252]. The extra content block, therefore, allows putting
richvdh marked this conversation as resolved.
Show resolved Hide resolved
a fallback representation that is actually designated for the timeline
into a separate `content['m.text']` field. Lastly, the `m.topic` content
richvdh marked this conversation as resolved.
Show resolved Hide resolved
block also serves as a good place for additional fields to be added by
other MSCs in the future.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking comment:

I don't entirely follow why we need an m.topic block as a place to put extra fields (unless we think that we're going to end up with topics inside other event types?) but maybe that's my lack of familiarity with extensible events.

@ara4n as the person that proposed this (I think?) can you clarify?


It is recommended that clients always include a plain text variant within `m.text` when
sending `m.room.topic` events. This prevents bad UX in situations where a plain
text topic is sufficient such as the public rooms directory.
Johennes marked this conversation as resolved.
Show resolved Hide resolved

Additionally, clients should duplicate the plain text topic into the existing
Expand All @@ -64,28 +70,25 @@ multiline details that are not suitable for room topics in a separate field
or event type.

On the server side, any logic that currently operates on the `topic` field is
updated to use the `m.topic` content block instead.

In [`/_matrix/client/v3/createRoom`], the `topic` parameter causes `m.room.topic`
to be written with a `text/plain` mimetype in `m.topic`. If at the same time an
`m.room.topic` event is supplied in `initial_state`, it is overwritten entirely.
A future MSC may generalize the `topic` parameter to allow specifying other mime
types without `initial_state`.

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 commonly have the same need for rich room topics as users
who already reside in the room. A future MSC may update these endpoints
to support rich text topics.

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 `m.text` content block of `m.room.topic` events.
updated to use the `m.topic` content block instead:

- In [`/_matrix/client/v3/createRoom`], the `topic` parameter should cause `m.room.topic`
to be written with a `text/plain` mimetype in `m.topic`. If at the same time an
`m.room.topic` event is supplied in `initial_state`, it is overwritten entirely.
A future MSC may generalize the `topic` parameter to allow specifying other mime
types without `initial_state`.
- In [`GET /_matrix/client/v3/publicRooms`], [`GET /_matrix/federation/v1/publicRooms`]
and their `POST` siblings, the `topic` response field should be 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 commonly have the same need for rich room topics as users
who already reside in the room. A future MSC may update these endpoints
to support rich text topics.
- 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 `m.text` content block of `m.room.topic` events.

## Potential issues

Expand Down Expand Up @@ -118,6 +121,7 @@ blocks might have their own prefixing requirements.
[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
richvdh marked this conversation as resolved.
Show resolved Hide resolved
[MSC4252]: https://github.com/matrix-org/matrix-spec-proposals/pull/4252
[sanitise]: https://spec.matrix.org/v1.12/client-server-api/#security-considerations
[server side search]: https://spec.matrix.org/v1.12/client-server-api/#server-side-search
[`m.room.topic`]: https://spec.matrix.org/v1.12/client-server-api/#mroomtopic
Expand Down
Loading