Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2025-12-20 16:38:37 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Remove legacy mentions (#2186)
Some checks failed
Spec / 🔎 Validate OpenAPI specifications (push) Has been cancelled
Details
Spec / 🔎 Check Event schema examples (push) Has been cancelled
Details
Spec / 🔎 Check OpenAPI definitions examples (push) Has been cancelled
Details
Spec / 🔎 Check JSON Schemas inline examples (push) Has been cancelled
Details
Spec / ⚙️ Calculate baseURL for later jobs (push) Has been cancelled
Details
Spec / 📢 Run towncrier for changelog (push) Has been cancelled
Details
Spell Check / Spell Check with Typos (push) Has been cancelled
Details
Spec / 🐍 Build OpenAPI definitions (push) Has been cancelled
Details
Spec / 📖 Build the spec (push) Has been cancelled
Details
Spec / 🔎 Validate generated HTML (push) Has been cancelled
Details
Spec / 📖 Build the historical backup spec (push) Has been cancelled
Details

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2025-09-21 11:44:16 +02:00 committed by GitHub
parent 2a8c0bc7b8
commit 2aacc1feda
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 27 additions and 156 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2186.removal Normal file
View file

@ -0,0 +1 @@
Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210).

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

@ -3,6 +3,9 @@
{{% changed-in v="1.7" %}}
{{% changed-in v="1.17" %}}: the legacy push rules that looked for mentions in
the `body` of the event were removed.
This module allows users to "mention" other users and rooms within a room event.
This is primarily used as an indicator that the recipient should receive a notification
about the event.
@ -38,19 +41,18 @@ encrypted as normal. To properly process mentions in encrypted rooms, events
must be decrypted first. See [receiving notifications](#receiving-notifications).
{{% /boxes/warning %}}
Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name),
[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and
[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to match if the `body` of
the event contains the user's display name or ID. To avoid unintentional notifications,
**it is recommended that clients include a `m.mentions` property on each event**.
(If there are no mentions to include it can be an empty object.)
{{% boxes/rationale %}}
{{% boxes/note %}}
In previous versions of the specification, mentioning users was done by
including the user's display name or the localpart of their Matrix ID and room
mentions were done by including the string "@room" in the plaintext `body` of
the event. This was prone to confusing and buggy behaviour.
{{% /boxes/rationale %}}
the event. When the `m.mentions` field was introduced, those push rules were
disabled if the `m.mentions` field was present.
To avoid unintentional notifications with clients and servers that still use
those push rules, **it is recommended that clients still include a `m.mentions`
property on each event**. (If there are no mentions to include it can be an
empty object.)
{{% /boxes/note %}}
#### Client behaviour

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

@ -382,6 +382,9 @@ The following `alt_aliases` values will NOT match:
**`contains_display_name`**
{{% changed-in v="1.17" %}}: this condition is deprecated and **should not be
used in new push rules**.
This matches messages where `content.body` contains the owner's display name in
that room. This is a separate condition because display names may change and as such
it would be hard to maintain a rule that matched the user's display name. This
@ -413,6 +416,9 @@ Parameters:
#### Predefined Rules
{{% changed-in v="1.17" %}}: the legacy default push rules that looked for
mentions in the `body` of the event were removed.
Homeservers can specify "server-default rules". They operate at a lower
priority than "user-defined rules", except for the `.m.rule.master` rule
which has always a higher priority than any other rule. The `rule_id`
@ -557,41 +563,6 @@ Definition:
}
```
<a id="_m_rule_contains_display_name"></a> **`.m.rule.contains_display_name`**
{{% changed-in v="1.7" %}}
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
does not have an [`m.mentions` property](#definition-mmentions)**.
Matches any message whose content contains the user's current display name
in the room in which it was sent.
Definition:
```json
{
"rule_id": ".m.rule.contains_display_name",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "contains_display_name"
}
],
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
]
}
```
<a id="_m_rule_is_room_mention"></a> **`.m.rule.is_room_mention`**
{{% added-in v="1.7" %}}
@ -626,44 +597,6 @@ Definition:
}
```
<a id="_m_rule_roomnotif"></a> **`.m.rule.roomnotif`**
{{% changed-in v="1.7" %}}
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
does not have an [`m.mentions` property](#definition-mmentions)**.
Matches any message from a sender with the proper power level whose content
contains the text `@room`, signifying the whole room should be notified of
the event.
Definition:
```json
{
"rule_id": ".m.rule.roomnotif",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "event_match",
"key": "content.body",
"pattern": "@room"
},
{
"kind": "sender_notification_permission",
"key": "room"
}
],
"actions": [
"notify",
{
"set_tweak": "highlight"
}
]
}
```
**<a id="mruletombstone"></a>`.m.rule.tombstone`**
Matches any state event whose type is `m.room.tombstone`. This is
@ -776,39 +709,6 @@ Definition:
}
```
##### Default Content Rules
<a id="_m_rule_contains_user_name"></a> **`.m.rule.contains_user_name`**
{{% changed-in v="1.7" %}}
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
does not have an [`m.mentions` property](#definition-mmentions)**.
Matches any message whose content contains the local part of the user's
Matrix ID, separated by word boundaries.
Definition (as a `content` rule):
```json
{
"rule_id": ".m.rule.contains_user_name",
"default": true,
"enabled": true,
"pattern": "[the local part of the user's Matrix ID]",
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
]
}
```
##### Default Underride Rules
**`.m.rule.call`**

24
data/api/client-server/definitions/push_ruleset.yaml
View file

@ -34,24 +34,6 @@ properties:
type: array
type: object
example: {
"content": [
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
],
"default": true,
"enabled": true,
"pattern": "alice",
"rule_id": ".m.rule.contains_user_name"
}
],
"override": [
{
"actions": [],
@ -113,12 +95,14 @@ example: {
],
"conditions": [
{
"kind": "contains_display_name"
"kind": "event_property_contains",
"key": "content.m\\.mentions.user_ids",
"value": "@alice:example.com"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.contains_display_name"
"rule_id": ".m.rule.is_user_mention"
},
{
"actions": [

24
data/event-schemas/examples/m.push_rules.yaml
View file

@ -3,24 +3,6 @@
"type": "m.push_rules",
"content": {
"global": {
"content": [
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
],
"default": true,
"enabled": true,
"pattern": "alice",
"rule_id": ".m.rule.contains_user_name"
}
],
"override": [
{
"actions": [],
@ -82,12 +64,14 @@
],
"conditions": [
{
"kind": "contains_display_name"
"kind": "event_property_contains",
"key": "content.m\\.mentions.user_ids",
"value": "@alice:example.com"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.contains_display_name"
"rule_id": ".m.rule.is_user_mention"
},
{
"actions": [