archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Remove legacy mentions (#2186)

Browse Source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
pull/2213/head
Kévin Commaille 2 months ago 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

1
changelogs/client_server/newsfragments/2186.removal
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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": [

Write Preview
Loading…
Cancel
Save