wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Make clear the thread root is not in the thread (#1677)

Browse source 
* Make clear the thread root is not in the thread

Signed-off-by: Andy Balaam <andy.balaam@matrix.org>

* Changlog entry for thread PR 1677 - thread roots not in thread

* Fix typo

* Add formatting for code values.

Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>

* Reword main timeline ID paragraph

* Use close to the original wording for the 'recurse' part of the 'in the thread' definition

* Remove note about thread roots being displayed in a thread

* Define the thread root

---------

Signed-off-by: Andy Balaam <andy.balaam@matrix.org>
Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
This commit is contained in:
Andy Balaam 2023-11-28 17:45:36 +00:00 • committed by GitHub
parent 634b24fb25
commit 6fe2ff4fa7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 29 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/1677.clarification Normal file
View file

@ -0,0 +1 @@
Clarify that thread roots are not considered within the thread.

20
content/client-server-api/modules/push.md
View file

@ -1070,16 +1070,16 @@ ahead), however if the `m.read.private` receipt were to be updated to
event D then the user has read up to D (the `m.read` receipt is now event D then the user has read up to D (the `m.read` receipt is now
behind the `m.read.private` receipt). behind the `m.read.private` receipt).
{{< added-in v="1.4" >}} When handling threaded read receipts, the server {{< added-in v="1.4" >}} When handling threaded read receipts, the server is to
is to partition the notification count to each thread (with the main timeline partition the notification count to each thread (with the main timeline being
being its own thread). To determine if an event is part of a thread the its own thread). To determine if an event is part of a thread the server follows
server follows the [event relationship](#forming-relationships-between-events) the [event relationship](#forming-relationships-between-events) until it finds a
until it finds a thread root (as specified by the [threading module](#threading)), thread root via an `m.thread` relation (as specified by the [threading
however it is not recommended that the server traverse infinitely. Instead, module](#threading)), however it is not recommended that the server traverse
implementations are encouraged to do a maximum of 3 hops to find a thread infinitely. Instead, implementations are encouraged to do a maximum of 3 hops to
before deciding that the event does not belong to a thread. This is primarily find a thread before deciding that the event does not belong to a thread. This
to ensure that future events, like `m.reaction`, are correctly considered is primarily to ensure that future events, like `m.reaction`, are correctly
"part of" a given thread. considered "part of" a given thread.
#### Server behaviour #### Server behaviour

22
content/client-server-api/modules/receipts.md
View file

@ -137,16 +137,20 @@ either a thread root's event ID or `main` for the main timeline.
Threading introduces a concept of multiple conversations being held in the same Threading introduces a concept of multiple conversations being held in the same
room and thus deserve their own read receipts and notification counts. An event is room and thus deserve their own read receipts and notification counts. An event is
considered to be "in a thread" if it meets any of the following criteria: considered to be "in a thread" if:
* It has a `rel_type` of `m.thread`.
* It has child events with a `rel_type` of `m.thread` (in which case it'd be the
thread root).
* Following the event relationships, it has a parent event which qualifies for
one of the above. Implementations should not recurse infinitely, though: a
maximum of 3 hops is recommended to cover indirect relationships.
Events not in a thread but still in the room are considered to be part of the * It has a `rel_type` of `m.thread`, or
"main timeline", or a special thread with an ID of `main`. * Following the event relationships, it has a parent event which references
the thread root with a `rel_type` of `m.thread`. Implementations should
not recurse infinitely, though: a maximum of 3 hops is recommended to
cover indirect relationships.
Events not in a thread but still in the room are considered to be in the "main
timeline". When referring to the main timeline as a thread (e.g. in receipts
and notifications counts) a special thread ID of `main` is used.
Thread roots are considered to be in the main timeline, as are events that are
related to a thread root via non-thread relations.
The following is an example DAG for a room, with dotted lines showing event The following is an example DAG for a room, with dotted lines showing event
relationships and solid lines showing topological ordering. relationships and solid lines showing topological ordering.

10
content/client-server-api/modules/threading.md
View file

@ -12,11 +12,11 @@ as by providing some context to what is going on in the thread but keeping the f
history behind a disclosure. history behind a disclosure.
Threads are established using a `rel_type` of `m.thread` and reference the Threads are established using a `rel_type` of `m.thread` and reference the
*thread root* (the first event in a thread). It is not possible to create a *thread root* (the main timeline event to which the thread events refer). It is not possible to create a thread from an event which itself
thread from an event which itself is the child of an event relationship (i.e., is the child of an event relationship (i.e., one with an `m.relates_to`
one with an `m.relates_to` property). It is therefore also not possible to nest property). It is therefore also not possible to nest threads. All events in a
threads. All events in a thread reference the thread root instead of the thread reference the thread root instead of the most recent message, unlike rich
most recent message, unlike rich reply chains. reply chains.
As a worked example, the following represents a thread and how it would be formed: As a worked example, the following represents a thread and how it would be formed: