Skip to content

Commit

Permalink
Rewrite/Split user's attributes away
Browse files Browse the repository at this point in the history 
user's user-given attributes now defined in
[MSC3865](matrix-org#3865)
  • Loading branch information
@Zocker1999NET
Zocker1999NET committed Aug 9, 2022
1 parent c31d8d9 commit 6bee650
Showing 1 changed file with 96 additions and 119 deletions.
215 changes: 96 additions & 119 deletions proposals/3864-room-nicknames.md
View file
Original file line number Diff line number Diff line change
@@ -1,132 +1,131 @@
# MSC3864: User-given nicknames & descriptions for rooms & users

User-given Nicknames or names loaded from an addressbook are great,
they allow you to personalize your experience in using an IM
while others do not need to change anything.
Like when you write with privacy-concerned users,
they might use a nickname for their account on their own,
but you may want to have them listed by their real name
or any other funny nickname you've given them.
Or people are using their display name to present statements like "(away until X)"
and you want to set an end to that (for yourself).

The same for groups, sometimes, the *global* room name works fine,
# MSC3864: User-given nicknames & descriptions for rooms

> This MSC is similar to [MSC3865](https://github.com/matrix-org/matrix-spec-proposals/pull/3865),
> which specifies user-given attributes for rooms.
> They were split because it makes more sense for now to store user attributes in another way
> and because it shall be possible to set a user-given name for any MXID restricted to a single room.
> However, they may share the same ideas and reasonings.
Sometimes, the *global* room name works fine,
but it would be funnier or easier for you to use another one.
Maybe because you've grouped similar rooms together into a (personal) space,
so parts of the name become irrelevant.
Like in a space called "My Long Cooperation Name",
where every room is called like "My Long Cooperation Name - IT Team Chat",
maybe shorter names like "IT Team" or "MLCN - IT Team" are better suited to you.
Or maybe because the admin is just too lazy or stubborn to improve the room name.
Or because you prefer them in another language to make your daily life easier.

Also, sometimes you just may want to append a description to a room,
so you know why you joined the room of have fast access to more information.
Especially when rooms change their descriptions,
but you still want to retain some links you connect to this group,
or these links do only apply for you.

Also, sometimes you just may want to append a description to a room or user,
so you know why you joined the room or are knowning the user.
Descriptions like "old class mate from XYZ School" can certainly improve your UX,
especially when users or rooms change their names due to personal reasons ("new name is cooler, duh")
and you stop recognizing who they are and need to ask them for their real life name
or read through the chat history (happened multiple times to me personally).
The same reasons apply to the room's avatar.
If you have a better one, you shall be able to select that one for yourself.


## Definitions

Further on, for the sake of simplicity and clarity:
- **global name** is the display name
- a user set for itself, visible globally to all other Matrix users.
- a room was given, visible globally to all other users who can see the room.
- **user-given name** refers to the name defined here a user shall be able to set,
only visible for itself, for other users or rooms,
replacing the global name.
- **global description** is the display description
a room was given, visible globally to all other users who can see the room.
- **user-given description** refers to the description defined here a user shall be able to set,
only visible for itself, for rooms,
extending the global description.
- the prefix **global** refers to the attribute which are set for a room,
visible globally to all Matrix users.
- the prefix **user-given** refers to the overrided/extended attribute a user defines for a room,
only visible to the former user.
These are newly defined by this MSC.


## Proposal


### Reasoning

Allowing users to set user-given names and descriptions for rooms and other users is useful
Allowing users to set user-given attributes for rooms is useful
because it let users increase their usability and accessibility to the Matrix infrastructure on their own and as required.
These names shall stay private to the user itself and may not be seen to others,
These attributes shall stay private to the user itself and may not be seen to others,
so users are able to choose what they see fit best
without thinking about privacy issues or the feelings of the room or users renamed.
without thinking about privacy issues or the feelings of the users in the rooms affected.

Adding this feature to the spec has the advantage that presumable most clients will implement support for displaying and hopefully also setting names and descriptions.
Adding this feature to the spec has the advantage
that presumable most clients will implement support for displaying
and hopefully also setting these user-given attributes.
It also allows a more unified experience accross all clients and devices
because user-given names and descriptions are synced using the home server of the user.
because user-given attributes are synced using the home server of the user.
For the same reason, this proposal includes a description of the expected user experience.

This proposal takes advantage of the already implemented
[client config feature](https://spec.matrix.org/unstable/client-server-api/#client-config) (a.k.a. `account_data`)
so the API and the server implementations do not need to change.
The user-given names and descriptions will be saved scoped to the room and in an own namespace.
Client configs are only visible to the user who set them and are synced accross all devices of the user,
The user-given attributes will be saved scoped to the room and in an own event type.
Client configs are only visible to the user who set them and are synced across all devices of the user,
which makes them a perfect fit for storing user-given names and user-given description.


### Implementation

For user-given names, a new event type called `m.name.user_given` may be added.
The content of this event will be `{"content": "<USER_GIVEN_NAME>"}`
For each state event of a room which present the aesthetic information about the room,
a new event type for the user-given counterpart shall be defined.
To get the new event type, the prefix `m.` will be replaced with `m.user_given.`.
Keeping the subpart `room` prevents name clashings with user's user-defined attributes
from [MSC3865](https://github.com/matrix-org/matrix-spec-proposals/pull/3865).
For the currently defined aesthetic state events, the new event types are listed below.

For user-given descriptions, a new event type called `m.description.user_given` may be added.
The content of this event will be `{"content": "<USER_GIVEN_DESCRIPTION>"}`
| Current room attribute name | User-defined event type | Content type |
| --------------------------- | ------------------------------- | ------------ |
| `m.room.name` | `m.user_given.room.name` | `string` |
| `m.room.avatar` | `m.user_given.room.avatar` | `URI` |
| `m.room.topic` | `m.user_given.room.description` | `string` |

Clients shall store & read those event types scoped to the selected / affected room.
This means they will GET / PUT following URL:
`/_matrix/client/v3/user/{userId}/rooms/{roomId}/account_data/{type}`
with parameters as follows:
- `{userId}`: The user id of the current user.
- `{roomId}`: The room id of the selected / affected room id.
- `{type}`: Either `m.name.user_given` or `m.description.user_given`
However, when rooms get a new aesthetic state event,
the same rules may apply to it to store its user-defined counterparts.

When setting user-given names and descriptions to other users,
clients shall scope the events to the room both users use to exchange 1:1 direct messages
(according to [MSC2199](https://github.com/matrix-org/matrix-spec-proposals/pull/2199)).
If a user may leave the last DM room, the user-given names and descriptions may be lost as well.
This behavior may or may not be expected, depending on the user's preference.
Clients may inform the user about this circumstance so they can make an informed choice.
The user-defined event must contain the keys `type` with its event type
and `content` which must have the same type as the overriden/extended room state event.
The following shall serve as an example value of the event type `m.user_given.room.name`,
which a client requested with the listed request:

- `GET /_matrix/client/v3/user/{userId}/room/{roomId}/account_data/m.user_given.room.name`

### User Experience

Clients shall replace most occurencies of the global name of a room with user-given name, if set.
Clients may still display the global name in some occurencies
according to the section [User Experience Issues](#user-experience-issues) below.
When the user wants to change the global name of a room,
or the user gets informed about a change of the global name of a room,
the global name may also not be replaced with the user-given name.
However in such events, the user-given name may be displayed as well.
```json
{
"content": "Support Group: Gaming",
"type": "m.user_given.room.name"
}
```

Clients shall append the user-given description to most occurencies of the global description of a room.
Clients shall display both in a way so the user can separate them and interpret them correctly.

Clients shall also replace most occurencies of another user's global name with its user-given name.
Aside from the DM room both users are using to exchange DMs,
this may include occurencies like in events or in member lists of other rooms.
When the user gets informed about a change of the global name of an user,
the global name may also not be replaced with the user-given name.
However in such events, the user-given name may be displayed as well, if not already.
### User Experience

For both rooms and other users, the client must not replace the Matrix ID of rooms / users.
Clients shall replace most occurencies of a room's global attribute with its user-given attribute.
When the user gets informed about a change of a global attribute of a room,
this occurency may not be replaced with the user-given attribute.
However, in such events, the user-given attribute may be displayed as well, if possible and not already.
The client must not replace the IDs of these rooms.

In some cases, the client may display both attributes (global and user-given) alongside each other,
if it makes sense in context of the attribute
and both attributes can be distinguished from one and another
(see [User Experience Issues](#user-experience-issues) for approaches on how to make them distinguishable).
However, the user-given attribute shall take precendece over the global one,
especially if the client can or wants to only display one of both
(see [Alternatives](#alternatives) for reasoning).
As an example, the client may display the name of a room as `USER_GIVEN_NAME (GLOBAL_NAME)`
with only the user-given avatar
but both the user-given description and the global description in this order
(assuming all user-given attributes were set).

If clients want to divert from the user experience declared here,
but still want to confirm to this MSC,
they may implement the user experience from above and their own approach
and make them configurable for the user.
As long as a configuration option is easily available,
clients may choose their own approach as the default.


## Potential Issues


### Implementation Issues

Some issues I discovered while writing or applying this MSC.
These are listed here as points open to discuss further.

#### Non-unique DM room

This issue will be solved by [MSC2199](https://github.com/matrix-org/matrix-spec-proposals/pull/2199).


### Privacy Issues

Because account data in general is sent unencrypted to the home server (for now),
Expand All @@ -138,46 +137,32 @@ however this is a task for another MSC to solve, preferably for all account data

### User Experience Issues

Using user-given names and forgetting that the user has configured them
Using user-given attributes forgetting that the user has configured them
could lead into the bad UX that users think their client stopped working correctly,
as a new name of the room or user is not displayed correctly.
This may be mitigated by clients by informing users about that the name is custom, either by:
- displaying user-given names in a custom font, style (e.g. **bold** or *italics*) or color
- displaying the global name aside in brackets ("USER_GIVEN_NAME (GLOBAL_NAME)", e.g. "Sweatheart (Erika Musterfrau)")
- this may only happen when reading messages of the room
- displaying the global name when hovering with the cursor over the user-given name

Clients may choose how they want to display and annotate user-given name and global name
by implementing none or any or some or all points from above as they see fit.
However, the user-given name shall be displayed as the primary name
(e.g. displaying as "**GLOBAL_NAME** (USER_GIVEN_NAME)"
or displaying the user-given name with less contrast than the global name
shall be prohibited, see [Alternatives](#alternatives) for reasoning).
as a new attribute of the room is not updated correctly.
This may be mitigated by clients by informing users about that the attribute is custom, either by:

The same problem should not occur in the same way to the user-given descriptions
as they shall expand the global description instead of replacing it.
However, clients should still display them either separated and labeled
or at least in way so users can separate them from one and another easily.
- displaying user-given attributes in a custom style (e.g. **bold** or *italics*), border or color,
- displaying the global attribute aside ("USER_GIVEN_NAME (GLOBAL_NAME)", e.g. "Support Group: Gaming (Gaming Buddies)"),
- displaying the global attribute when hovering with the cursor over the user-given attribute,
- or by another, similar approach.

Clients may choose how they want to display and annotate user-given attributes and global attributes
by implementing none or any or some or all points from above as they see fit.

## Alternatives

User-given names and descriptions set for others users only may be stored into the general account data.
This would circumvent the problem with [non-unique DM rooms](#non-unique-dm-room) particular for this MSC.
However, clients may still need to solve this problem for other implementations,
so no complexity would be saved in the end.
It instead places them near other configurations like client-dependent (not room-dependent) configuration options,
and the user-given names and description may be lost when another user changes its Matrix ID
and it also lets the implementation for rooms and users differ more.
## Alternatives

Conceptually, the user-given name could also be displayed as a secondary attribute alongside the global name
("GLOBAL_NAME (USER_GIVEN_NAME)", e.g. "Erika Musterfrau (Sweatheart)").
Conceptually, the user-given attribute could also be displayed as a secondary attribute alongside the global attribute
("GLOBAL_NAME (USER_GIVEN_NAME)", e.g. "Gaming Buddies (Support Group: Gaming)").
This could prevent some [UX issues](#user-experience-issues),
however this prevents users to customize their experience in certain ways
(e.g. when they don't want to read the global name).
With this implementation, a user is still able to display (parts of) the global name
as they like by adding it to the user-given name theirselves.
It only would not be updated automatically.
Clients which do not want to agree may implement both approaches and make the configurable to the user
as stated above in [User Experience](#user-experience).


## Security considerations
Expand All @@ -190,7 +175,7 @@ ans so should not create any security-releated issues.

Until this MSC is merged, clients shall use event type names
where the `m.` prefix is replaced with `work.banananet.msc3864.`
(e.g. use `work.banananet.msc3864.name.user_given` instead of `m.name.user_given`).
(e.g. use `work.banananet.msc3864.user_given.room.name` instead of `m.user_given.room.name`).
Event types with the former prefix are further called *official event types*.
event types with the latter *unstable event types*.

Expand All @@ -206,11 +191,3 @@ prefereable automtatically and in the background when finding such a event type.
The migration policy might cause old clients to "lose" the user-given ones,
however hopefully this will move clients to migrate as well
and users to update their clients.


## Dependencies

This MSC formaly depends on [MSC2199](https://github.com/matrix-org/matrix-spec-proposals/pull/2199).
However, as long as clients can resolve an 1:1 DM room successfully by other means
(hopefully compatible to other clients as well),
clients should be able to implement this one.

0 comments on commit 6bee650

Please sign in to comment.