From 2aacc1feda4bd949d1148755ab724718f03c4a3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Sun, 21 Sep 2025 11:44:16 +0200 Subject: [PATCH] Remove legacy mentions (#2186) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../client_server/newsfragments/2186.removal | 1 + content/client-server-api/modules/mentions.md | 22 ++-- content/client-server-api/modules/push.md | 112 +----------------- .../definitions/push_ruleset.yaml | 24 +--- data/event-schemas/examples/m.push_rules.yaml | 24 +--- 5 files changed, 27 insertions(+), 156 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2186.removal diff --git a/changelogs/client_server/newsfragments/2186.removal b/changelogs/client_server/newsfragments/2186.removal new file mode 100644 index 00000000..c40f001f --- /dev/null +++ b/changelogs/client_server/newsfragments/2186.removal @@ -0,0 +1 @@ +Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210). diff --git a/content/client-server-api/modules/mentions.md b/content/client-server-api/modules/mentions.md index 0cdbad77..ea21f651 100644 --- a/content/client-server-api/modules/mentions.md +++ b/content/client-server-api/modules/mentions.md @@ -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 diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 15639995..a8327b40 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -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: } ``` - **`.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" - } - ] -} -``` - **`.m.rule.is_room_mention`** {{% added-in v="1.7" %}} @@ -626,44 +597,6 @@ Definition: } ``` - **`.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" - } - ] -} -``` - **`.m.rule.tombstone`** Matches any state event whose type is `m.room.tombstone`. This is @@ -776,39 +709,6 @@ Definition: } ``` -##### Default Content Rules - - **`.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`** diff --git a/data/api/client-server/definitions/push_ruleset.yaml b/data/api/client-server/definitions/push_ruleset.yaml index 0a2148e0..980c915e 100644 --- a/data/api/client-server/definitions/push_ruleset.yaml +++ b/data/api/client-server/definitions/push_ruleset.yaml @@ -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": [ diff --git a/data/event-schemas/examples/m.push_rules.yaml b/data/event-schemas/examples/m.push_rules.yaml index 639c6ec7..6e6b41a4 100644 --- a/data/event-schemas/examples/m.push_rules.yaml +++ b/data/event-schemas/examples/m.push_rules.yaml @@ -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": [