diff --git a/content/extensions.md b/content/extensions.md index 467705045..4598c1074 100644 --- a/content/extensions.md +++ b/content/extensions.md @@ -19,6 +19,6 @@ The XMPP Standards Foundation develops extensions to XMPP in its XEP series. Thi XEP series data can be explored using [data.xmpp.net/explore](https://data.xmpp.net/explore/). -Good places for developers to start are the [compliance suites](/about/compliance-suites/), as well as the [technology overview pages](/about-xmpp/technology-overview/). For further reading, we suggest the independent [Modern XMPP project](https://docs.modernxmpp.org/) which attempts to improve the quality of user-to-user messaging applications that use XMPP. +Good places for developers to start are the [compliance suites](/about/compliance-suites/), as well as the [technology overview pages](/about-xmpp/technology-overview/). For further reading, we suggest the [implementation guidelines](/implementation-guidelines) which attempt to improve the quality of user-to-user messaging applications that use XMPP. {{< xeps-table >}} diff --git a/content/implementation-guidelines/2019-01-brussels.md b/content/implementation-guidelines/2019-01-brussels.md new file mode 100644 index 000000000..5ae07cd74 --- /dev/null +++ b/content/implementation-guidelines/2019-01-brussels.md @@ -0,0 +1,178 @@ +--- +Title: UX Sprint (January 2019, Brussels) +layout: single-implementation-guidelines +--- + +These are the archived notes from the Jan 2019 Brussels sprint, +which focused primarily on discussing various UX issues facing +the community as a whole. There is an associated +[wiki page](https://wiki.xmpp.org/web/Sprints/2019_January_Brussels). + +The notes were taken in real-time by volunteers during the discussions. +As such, they are far from editorially perfect, and are not intended as +documentation. Relevant items around which consensus was formed are +either already merged or in the process of being merged into the actual +documentation. + +I don't know why Tux is here, but I'll let him stay. + +- - - + +``` + .-"""-. + ' \ + |,. ,-. | + |()L( ()| | + |,' `".| | + |.___.',| ` + .j `--"' ` `. + / ' ' \ + / / ` `. + / / ` . + / / l | + . , | | + ,"`. .| | + _.' ``. | `..-'l + | `.`, | `. + | `. __.j ) + |__ |--""___| ,-' + `"--...,+"""" `._,.-' +``` + +## TODO + +- Extend https://wiki.xmpp.org/web/Usability/Glossary + +### Daniel’s list +* What to name things? + * Common Jabber vocabulary for Groups, 'Jabber ID', bookmarks, "MUC members / participants" + * Persons; (preference of roster name, pep name, local sync name (address book). + * Persons in MUC (order of preference of room nick, roster name, pep name, …) + * order of people in member list admins first?, alphabetical? (see affiliations) + * Groups / Chats (preference of description, subject, local part, name, bookmark name, auto generated name) + * do not get MUC name from identity name but from disco form fields because identity name is set to localpart on some servers + * Do we want to replace a referenced nick with the local version? + * Ad hoc, Impromptu group chat; come up with a cool default settings like members only, non-anon, allow pm?, allow subject change, allow invite. What to expose +Behavioral changes in impromptu MUCs (send chat states, display read markers, e2ee by default, prefer 1:1 instead of PM when contacting a participant) and how to recognize and impromptu chat (isMemberOnly && isNonAnon) +* Affiliations + * Do we need an owner. Should in a three person chat someone be the 'owner' + * Administrators might make sense. But maybe we want to show owner and admin as the same. + * Maybe it makes sense to make everyone owner and then call owner the admin + +* Do we need different profiles? + * Private, non-anon + * Public + * Announcements. w/o presence broadcast, moderated + * should those profiles be locked afterwards + + +* Do we want to keep bookmarks or just use it as a sync mechanism? + * open/close conversations when bookmark created / autojoin flag removed? + * do we also leave when bookmark is removed? Does that work? this basically means no join without bookmark. 'remove bookmark' (w/o leave) can not be an action anymore + + +## Naming things?! + +* Jabber ID? JID? XMPP address? + * "Jabber" trademark + * "JID" widely used but might be a more technical term + * "something address" is clear to people + * "XMPP" is usually hard to remember, "Jabber" is more friendly to the ear + * Jabber is the community, XMPP is the protocol + * What about calling it "Conversations ID", or "Converse ID", or "Movim ID", all at the same time. Might be confusing for users when they use multiple clients but most don't. + * Some other protocols use "username" (with a hint for the default domain) + +Consensus: "XMPP Address"? (until another user-friendly term for "XMPP" can be found/agreed upon) + + +## Results / Consensus + + +### XMPP Address / Jabber ID + - XMPP Address input: Always use one field. Never split into localpart and domain part. If possible do auto-complete on the server part in drop down + + +### Group chats / channels: + - Private group chat (or groupchat) + + - members only + - JID visibility: all + - MAM: yes + - not listed (non public) + - persistence + - users can invite. default off. (does this need to be configurable?) + - subject editability: owner only (probably make it configurable?) + - disallow pm + + - Public channel + - public / everyone can join + - MAM: yes + - listed: yes + - persistent + - JID: visibility anonymous + - subject editability: admins only (probably make it configurable) + - Possibility to omit the words 'private' and 'public' later down the UI flow and just talk about 'groupchat' and 'channel' (for example when constrained on screen estate) + + - recognize on members only AND visible JIDs AND not listed, everything else is a public channel. but a client should maybe warn before entering a public channel that makes your JID public. Those three 'detection properties' are immutable for private group chats + + - private group chats use randomized, auto generated JID (always on the server’s own MUC host) + - public channels always ask for bare JID on create (auto suggest of know MUC hosts) + - UI suggestion. ask for name first. Then normalize to local part of JID. But let user change the JID if they want to + + +Group chats and channels should be clearly distinguished visually. + +| | Groupchat | Channel | Immutable for groupchats | +|:-----------------|:---------:|:-------:|:------------------------:| +| Members-only | Yes | No | X | +| Reveal JIDs | Yes | No | X | +| Publicly listed | No | Yes | X | +| Persistent | Yes | Yes | | +| MAM enabled | Yes | Yes | | +| Subject editable | No | No | | +| PMs | No | Yes | X | + + +### Terminology + +People in the group chat / channel: Participants + + +| Affiliations | In groupchats | In channels | +|:-------------|:-------------:|:-----------:| +| none | N/A ** | Guest | +| member | - | - | +| admin | *Admin* (\*) | Admin | +| owner | Owner | Owner | + +Roles should not be used anymore. + +(\*) A group chat will display an existing admin as such but it will not encourage/allow someone to be promoted to admin. UI options in group chats only allow a member to become an owner but not admin. So admins are discouraged by the UI but will be displayed as such if the end up being one for some reason. + +clients MAY create an 'advanced view' that displays roles as well. + +** Everybody is a member in groupchats + + +### Suggested order of what to call an individual +message: roster name, (address book), user nickname, localpart +groupchat message: roster name, (address book), user nickname, resource (mentions refer to resource. if you do proper references you can live replace it with the 'nice' name) +channel message: resource +roster: roster name, user nickname, bare JID +profile: roster name, user nickname, bare JID + +Avatar display should follow the same order + +### Bookmarks +Unbookmarking a bookmark doesn’t do magic leave on any devices +when receiving set/unset autojoin will join/leave on all devices +leave/join will unset/set the autojoin flag (exposed as a choice to the user) +clients should offer global sync-opt-out (Don’t adhere to autojoin) +clients should store the list of groupchats open, unrelated to the autojoined bookmarks + +Summary: clients store the list of open chats (groupchats or not) and restore it on next start; on receiving a bookmark with a new autojoin from PEP, add the room to that list and open it; on receiving one without an autojoin, remove it from that list and close it; on joining a room add an autojoin bookmark; on leaving a room ask whether to leave it globally (then remove the autojoin from the bookmark), or to leave it locally (then remove the bookmark). + +## Places to update/remove + +https://wiki.xmpp.org/web/Usability/Glossary +https://wiki.xmpp.org/web/Easy_Group_Chats diff --git a/content/implementation-guidelines/_index.md b/content/implementation-guidelines/_index.md new file mode 100644 index 000000000..2b10a2ae9 --- /dev/null +++ b/content/implementation-guidelines/_index.md @@ -0,0 +1,29 @@ +--- +title: Implementation Guidelines +layout: single-implementation-guidelines +--- + +## Overview + +**Modern XMPP** is an independent project launched to improve the quality of user-to-user messaging applications +that use XMPP. [XMPP](/) is a mature open standard for internet messaging. If you are reading +this, you have probably heard of it. + +We are developing a handful of simple documents aimed at people who wish to build on top of XMPP. The recommendations are derived from healthy discussions between developers from multiple XMPP projects and other members of the XMPP community. + +Our recommendations highlight only the XEPs you need to implement for a modern messaging application, +ignoring historical cruft and excessive backwards-compatibility. + +We also intend to provide a comprehensive set of guidelines for UI and UX design. Developing a client was never just about the protocol. In fact in most cases the protocol is a secondary concern. Having a concrete set of guidelines will help to provide a more uniform user experience between different applications, ensuring they use the same terminology, and provide interoperable feature sets. + +Times change, and we expect our recommendations to evolve over time. Our guidelines will be versioned, +and thus make it possible to identify and weed out software that falls behind the times. + +## Current status + +It is early days. We are still building the foundations of what will become the initial set of documents. Nevertheless, we already have a bunch of stuff documented that developers of XMPP software (both new and experienced) will find useful. This includes [design guidelines](/implementation-guidelines/design) and lower-level [protocol implementation recommendations](/implementation-guidelines/protocol). + +If you're interested in joining us, our primary discussion venue is our *channel* which can be reached at: + +- XMPP: [modernxmpp@rooms.modernxmpp.org](xmpp:modernxmpp@rooms.modernxmpp.org?join) +- Web: [chat.modernxmpp.org](https://chat.modernxmpp.org/) diff --git a/content/implementation-guidelines/design.md b/content/implementation-guidelines/design.md new file mode 100644 index 000000000..7fe66f18d --- /dev/null +++ b/content/implementation-guidelines/design.md @@ -0,0 +1,237 @@ +--- +Title: Client Design Guidelines +layout: single-implementation-guidelines +--- + +This document lays out a set of guidelines for designing Modern XMPP clients. For contributions, +please [open an issue or pull request](https://github.com/modernxmpp/modernxmpp) at Github for discussion. + +## Registration + +{{< info-block type="todo" / >}} + +## Initial configuration + +At initial startup, a client should present a welcome screen, to prompt the user for their JID, +and a password. Optionally, a button or link to provide other forms of credentials may be included. + +If the client has an out-of-band configuration mechanism, or it can query the OS for sensible defaults, +it may use these. + +## Configuration options + +List recommended configuration options. + +### Account + +| Option | Description | +|:-------|:----------------------| +| JID | The user's JID | +| Password | The user's password | + +### Network + +Support for these options is OPTIONAL, but **not** recommended. They are only needed for testing/development purposes or working around misconfigured server deployments. If included in the client, they MUST NOT be requested by default at startup, but should be accessible through an advanced options interface. + +| Option | Description | +|:--------------------|:---------------------------------------------| +| Connect host | The network hostname to connect to | +| Connect port | The network port to connect to | +| TLS Mode[^tls-mode] | Multiple choice: "STARTTLS" or "Direct TLS" | + +Both of the above should be automatically discovered from DNS, according to the [rules in RFC 6120](/rfcs/rfc6120.html#tcp-resolution). +Clients that support other connection mechanisms, such as BOSH, SHOULD also implement [XEP-0156](/extensions/xep-0156.html). + +### Deprecated options + +Support for these options is NOT RECOMMENDED. + +| Option | Description | Notes | +|:-------------|:-----------------------------------------|:--------| +| Resource | The resource to request from the server | see [Resource generation](/implementation-guidelines/protocol#resource-generation) | +| Priority | The priority to include in presence | 0 | + +## User status + +The client, by default, MUST NOT include any status messages in its presence, unless they are chosen by the user. Built-in status messages that +convey the same meaning as the user's selected 'show' value (e.g. "Available", "Do not disturb") are not allowed. + +Allowing the user to set a status message is an OPTIONAL feature. + +## Contact list + +### Terminology + +In its interface, the client MUST NOT use the technical term "roster", but MUST instead use the term "contact list" (or a suitable translation) +where necessary. See the main "Terminology" section for more information. + +### Offline contacts + +The client MUST display offline contacts by default, and allow sending messages to them, as for online contacts.. + +### Sorting of contact list + +The client MUST sort the contact list. Either in [lexicographical order](https://en.wikipedia.org/wiki/Lexicographical_order) by contact name or +chronologically by the time of the last message exchanged with that contact. + +{{< info-block type="note" >}} +Historically, some clients have sorted by presence (available, offline, busy, etc.) as a secondary sorting category. Due to the rise in mobile clients which always consider themselves "available", presence is not always a reliable indicator that a contact is available to chat. +{{< /info-block >}} + +If sorting chronologically and/or by presence, clients MUST NOT rearrange the +contacts list while fetching history, or when the contact list has focus. +The definition of "focus" depends on the context, but may be the cursor hovering +over the list, the list pane being visible, or the list being selected in a +screen reader or during tab selection. + +### Visualizing status + +The client MUST display status messages of contacts when present. It MAY also provide visual indication of the contact's status ('show'), but +SHOULD NOT rely on color alone to distinguish different status values[^color]. + +{{< info-block type="todo" >}} +Describe how to display multiple remote resources. +{{< /info-block >}} + +## Conversation view + +### Message states + +#### Outgoing messages + +A client must be able to unambiguously display the following outgoing message states: + +* Message pending delivery +* Message delivered to server +* Message delivered to contact +* Message read by contact +* Delivery error for message + +{{< info-block type="todo" >}} +Add table or flowchart +{{< /info-block >}} + +## Notifications + +Carbons, notifications for new messages in MAM + +## Error handling + +Obey error types (modify, cancel, wait, etc.) + +Do display error text + +## Multiple accounts + +Support for multiple accounts is OPTIONAL. + +{{< info-block type="todo" >}} +Research recommendations for the best way to handle multiple accounts. E.g. merge contacts, or not. +Not required. Describe how to display multiple accounts in a single client? +{{< /info-block >}} + +## Group chat + +You can find more details about [group chats here](/implementation-guidelines/groupchat). + +## Documentation + +Clients should have documentation covering essential functionality, including: + +{{< info-block type="todo" >}} +List of recommended documentation topics, e.g. how to add a contact +{{< /info-block >}} + +## Privacy + +Clients must not reveal full JID. Don't query unsubscribed contacts. + +{{< info-block type="todo" >}} +Probably belongs in protocol reference. Probably some things relevant to UI that should be mentioned, however. +{{< /info-block >}} + +## Names + +When displaying messages received from a remote JID, either within a one-to-one or multi-user chat, clients need to show a human-readable +name for that sender. + +There are multiple sources for such a display name, which depend on the context (e.g. whether the conversation is one-to-one or a group chat). + +### Name sources + +Valid sources are: + +Roster +: If the contact is in the user's roster, and the user has set a custom name. + +Address book +: Platform-dependent. If the application is somehow linked to the user's address book and is able to access a contact's information there. + +User nickname +: A nickname published by the sender in PEP per [XEP-0172](/extensions/xep-0172.html). + +Resource +: The resource of the sending JID. + +Local part +: The part of a bare JID before the '@' symbol. + +Bare JID +: The sending JID with any resource removed. + +### Contexts + +The kind of view where a name is displayed decides which sources should be used. Since most sources are optional, they +should be checked in the order described by the table below, displaying the first one available. + +| View type | Name priorities | +|-------------------------|-----------------------------------------------------------| +| Conversation - normal | Roster name, (Address book), User nickname, Local part | +| Conversation - group | Roster name, (Address book), User nickname, Resource (\*) | +| Conversation - channel | Resource | +| Contact list | Roster name, User nickname, Bare JID | +| User profile | Roster name, User nickname, Bare JID | + +(\*) Mentions refer to resource. if you do proper references you can live replace it with the 'nice' name. + +Avatar display should follow the same order + +## Auto-generated colors + +A client may want to associate a color with a user. Example use cases for this include, but are not limited to: + +- Dummy avatars in contexts where an avatar cannot be or has not yet been retrieved +- Coloring the user name in a conversation log (be aware that this needs to be done very carefully to be accessible!) + +To generate a color for a user, the algorithm described in [XEP-0392](/extensions/xep-0392.html) MUST be used. + +### Generator input based on context + +The generator described in XEP-0392 needs a text input to operate and for which a deterministic color will be generated. + +The following table lists which strings to use as input for the generator: + +| View type | Generator Input | +|-------------------------|---------------------| +| Conversation - normal | Normalised Bare JID | +| Conversation - group | Normalised Bare JID | +| Conversation - channel | Resource | +| Contact list | Normalised Bare JID | +| User profile | Normalised Bare JID | + +### Contrast ratio considerations + +To provide a good contrast ratio for accessibility of the resulting user interface, the guidelines from [^color] should be obeyed. XEP-0392 intentionally allows the implementation to pick a saturation and lightness value based on the environment to allow for high contrast. + +Contrast considerations apply between the generated color and the background, as well as for text rendered on top of the generated color (for example in a dummy avatar). + + + +[^color]: Resources for the use of color in interface design: + + * [WCAG 2.1: Understanding Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html) + * [Color contrast checker](https://webaim.org/resources/contrastchecker/) + +[^tls-mode]: This is presented as a multiple-choice option. A checkbox labeled e.g. "Direct TLS" + may confuse users by implying that the opposite of "Direct TLS" is potentially "No TLS". Security is + not an option, and TLS is always used. This option is about what style the server supports. diff --git a/content/implementation-guidelines/groupchat.md b/content/implementation-guidelines/groupchat.md new file mode 100644 index 000000000..a9fdd55c2 --- /dev/null +++ b/content/implementation-guidelines/groupchat.md @@ -0,0 +1,146 @@ +--- +Title: Multi-user Chats +layout: single-implementation-guidelines +--- + +## Types of chat + +There are two kinds of multi-user chat. Private *group chats*, and public *channels*[^rationale-gc]. + +### Properties + +To detect if a multi-user chat is a *group chat* or a *channel* + +{{< table >}} +| | MUC Configuration variable (1) | Group chat | Disco Feature (2) | Channel | Disco Feature (2) | +|:-----------------|:-------------------|:-----------|:---------------|:--------|:---------------| +| Persistent | muc#roomconfig_persistentroom | Yes | muc_persistent | Yes | muc_persistent | +| MAM enabled | **Prosody** muc#roomconfig_enablearchiving **ejabberd community**: mam **ejabberd saas** muc#roomconfig_mam | Yes | urn:xmpp:mam:2 | Yes | urn:xmpp:mam:2 | +| Subject editable | muc#roomconfig_changesubject | No | muc#roomconfig_changesubject to `false` | No | muc#roomconfig_changesubject to `false` | +| Members-only | muc#roomconfig_membersonly | Yes (3) | muc_membersonly | No | muc_open | +| JIDs revealed | muc#roomconfig_whois | Yes (3) | muc_nonanonymous| No | muc_semianonymous | +| Publicly listed | muc#roomconfig_publicroom | No (3) | muc_hidden | Yes | muc_public | +| PMs | muc#roomconfig_allowpm | No (3) | muc#roomconfig_allowpm to `none` | Yes | muc#roomconfig_allowpm to `anyone` | +{{< /table >}} + +(1) As defined in [XEP-0045: Multi-User Chat - 16.5.3](/extensions/xep-0045.html#registrar-formtype-owner) + +(2) As defined in [XEP-0045: Multi-User Chat - 16.3](/extensions/xep-0045.html#registrar-features) + +(3) Immutable for *group chats*. + +Options marked `(3) Immutable` should be used when creating group chats, and also as a means of detection. These options may be hidden or greyed out in a configuration dialog. The other options are recommendations. + +#### About PMs + +While it is possible to entirely prevent PMs from being sent with +[`muc#roomconfig_allowpm`](/extensions/xep-0045.html#privatemessage), +clients should prefer using JIDs when `muc#roomconfig_whois` is set to `anyone`. + +In channels, if the initiating client has access to revealed JIDs (with +`muc#roomconfig_whois` set to `moderators`), clients may want to refrain from +using them to prevent disclosing the JID of the user initiating the chat, +unless the recipient already knows them from another venue (e.g., the +recipient is in their roster). + +### Terminology + +People in the *group chat* / *channel*: *Participants* + +Roles are not displayed and cannot be modified through the UI. + +| Affiliations | In group chats | In channels | +|:-------------|:--------------:|:-----------:| +| none | N/A ** | Guest | +| member | - | - | +| admin | *Admin* (\*) | Admin | +| owner | Owner | Owner | + +(\*) A *group chat* will display an existing admin as such but it will not encourage/allow +someone to be promoted to admin. UI options in *group chats* only allow a member to become +an owner but not admin. So admins are discouraged by the UI but will be displayed as such +if they end up being one for some reason. + +(\*\*) Everybody is a member in *group chats* + +Clients MAY create an 'advanced view' that displays roles as well. + +## User nickname + +When joining a group chat, a client needs to select a nickname to use. There are multiple +sources from which this name may be selected. The client should use the following sources +in order: + +Bookmark +: If the chat is present in the user's bookmarks and has a nickname present (as the resource). + +Reserved name +: A chat [may be queried](/extensions/xep-0045.html#reservednick) to fetch the + name that is registered by the user for that chat. + +User nickname (PEP) +: The name stored in the user's account according to + [XEP-0172](/extensions/xep-0172.html#manage). + +User nickname (vCard) +: The name stored in the user's vCard as `NICKNAME`. + +Local nickname +: (Optional, not recommended[^local-nickname]) A nickname previously configured by the user in this client instance. + +JID username +: The username portion of the user's JID (i.e. before the '@'). + +### Other user's names + +The display of other user's names is covered in the [general UI recommendations](/implementation-guidelines/design#names). + +## Bookmarks + +Figuring out which group chats to join is the client’s job. For that it +should store the list of group chats to rejoin automatically on the +server, named bookmarks. Three possible protocols exist for this: + +- [XEP-0402](/extensions/xep-0402.html) which is the + current preferred method +- [XEP-0048 1.1](/extensions/xep-0048.html), recently + deprecated but still in use by some clients +- [XEP-0048 1.0](/extensions/attic/xep-0048-1.0.html), + in wide use, based on + [XEP-0049](/extensions/xep-0049.html) + +In order to see the same set of bookmarks as every other client the +user might be using, it is recommended to implement **XEP-0048 1.0** first +and foremost when the user's account may be shared with other clients. + +This legacy protocol however doesn’t support notifications when the bookmarks +change due to another client or the server. To avoid this issue, a modern client +should also implement **XEP-0402** ("PEP Native Bookmarks"), but use it *only* if the account +advertises 'urn:xmpp:bookmarks:1#compat' (as defined in [XEP-0402 paragraph 5.3 +Compatibility](/extensions/xep-0402.html#compatibility)). + +Implementing XEP-0048 1.1 is not recommended in modern clients. + +The following table summarizes the implementation recommendations described in this section: + +| XEP | Implement | Use | +|--------------------------------------------|------------------------------------------|-----------------------------------------------------------------------------| +| XEP-0048 1.0 (Private XML storage) | Yes (for backwards compatibility) | When `urn:xmpp:bookmarks:1#compat` **is not** advertised by the server on the user's account. | +| XEP-0048 1.1 (PEP storage, single-item) | No (deprecated in favour of XEP-0402) | Never | +| XEP-0402 (PEP storage, multi-item) | Yes | When `urn:xmpp:bookmarks:1#compat` **is** advertised by the server on the user's account. | + +## Private messages + +Clients must always use real JIDs for messaging privately within a *group chat* if (and only if) JIDs are publicly visible to all participants.[^pm-realjid] + + + +[^rationale-gc]: Rationale [group chats](/implementation-guidelines/rationale#group-chats) +[^local-nickname]: To avoid requiring the user to configure a nickname manually on each device, shared cross-device stores such as PEP and vCard should be preferred. +[^pm-realjid]: If real JIDs are known to all participants, it is preferable to use that for private communication to avoid confusion. Through-MUC PMs have the following disadvantages: + + - Only work while connected to the group chat + - Do not interact well with multiple devices (e.g. not all of a recipient's devices may be in a group chat) + - Can cause confusion if talking to the same person through different views (e.g. if the person is already a contact in your roster, and you already have a chat open with them) + + However if the sending user is an admin of a room where JIDs are hidden, using a real JID will reveal the admin's private JID to the recipient. Either warn the sender that their JID will be revealed, or always use the in-room JID in such channels. diff --git a/content/implementation-guidelines/invites.md b/content/implementation-guidelines/invites.md new file mode 100644 index 000000000..78ab8b453 --- /dev/null +++ b/content/implementation-guidelines/invites.md @@ -0,0 +1,123 @@ +--- +Title: Registration through invitation +layout: single-implementation-guidelines +--- + +It is possible to create invitation links in XMPP. There are currently a few +types of invitation possible, e.g. you may be invited to register on a server, +or be invited to add someone as a contact, or both. + +## Invitation types + +There are three types of invitation: + +- [Account-only](#account-only) +- [Subscription-only](#subscription-only) +- [Account-and-subscription](#account-and-subscription) + +They are described individually in the following sections. + +### Account-only + +This type of invitation can be used by server operators to allow +people to create accounts on their server, without needing to open up +registration to the public. + +#### Format + +Invitation to register an account on a given domain (e.g. 'example.com'): + +``` +xmpp:example.com?register;preauth=3c7efeafc1bb10d034 +``` +or an invitation to register an account with a **specific** username (e.g. +'romeo') only: + +``` +xmpp:romeo@example.com?register;preauth=3c7efeafc1bb10d034 +``` + +See [XEP-0445][] for how to register an account using this type of invitation. + +### Subscription-only + +This invitation type can be shared with someone who you would +like to add you as a contact. Unlike a normal XMPP subscription request, these +invitations can be shared to people via any mechanism (e.g. email, SMS, web) +and if you don't know the recipient's XMPP address or they don't yet have one. + +A potential contact invites you to communicate with them: + +``` +xmpp:contact@example.com?roster;preauth=3c7efeafc1bb10d034 +``` + +The protocol to handle this type of invitation is specified in +[XEP-0379][]. After following the protocol, you will have a mutual presence +subscription with `contact@example.com`. + +If the user does not currently have an account, the client must walk +them through the account registration process on a suitable XMPP service. + +### Account-and-subscription + +The same as a subscription-only invite, but it indicates you +are able to use the token to also register an account on the contact's +domain, signalled by the presence of `ibr=y` in the URI parameters: + +``` +xmpp:contact@example.com?roster;preauth=3c7efeafc1bb10d034;ibr=y +``` + +If the recipient of such an invite does not yet have an XMPP account, their +client should follow the *Registration protocol* section of this document. +After completing the registration, the user will automatically be subscribed +to the sender of the invitation. + +If the recipient already has an XMPP account, the invitation should be +handled the same as a subscription-only invitation documented above, +and follow the protocol defined in [XEP-0379][]. + +## Protocols + +There are three standards governing the creation and consumption of invitations: + +- [XEP-0401][] - describes how to create new invitations (of all types). +- [XEP-0445][] - describes how to register an account using an account-only or account-and-subscription invitation. +- [XEP-0379][] - describes how to convert an invitation (subscription-only or account-and-subscription types) into a roster subscription. + +### Registration protocol + +The account-only and account-and-subscription invitation types allow a recipient +to create an account on a server (which may otherwise have closed registration). +XMPP clients can use these invitation types to create an account by following +the protocol in [XEP-0445][]. + +## Creating an invitation + +To create an invitation, use [XEP-0401: Ad-hoc Account Invitation Generation][XEP-0401]. +Your server may also provide a mechanism (e.g. web interface or command-line +utility) to create invitations. + +Services may restrict the types of invitation that can be created, depending +on policy. E.g. private servers may allow anyone to create contact invitations, +but only allow administrators to create account invitations. + +When using XEP-0401, the server will provide at minimum an `xmpp:` URI that can be interpreted by any compatible XMPP client. However this URI SHOULD NOT be shared directly by clients. It is generally likely that the recipient of an invite does not yet have an XMPP client installed and configured. + +Instead, if the server provides a `landing-url` in the response, the client SHOULD share this URL with contacts. Otherwise it SHOULD use the URI in combination with a landing page (which may be hosted by the client developer or other entity) to generate a `https://` URL suitable for sharing. One such landing page implementation can be found at [ge0rg/easy-xmpp-invitation](https://github.com/ge0rg/easy-xmpp-invitation). +Sharing the URL can be done by visually displaying a QR code on the user's screen (if the contact is in physical proximity) or e.g. through the platform's own sharing mechanism (to share via SMS, email, social apps, etc.) + +## Guidance for landing pages + +As well as embedding the XMPP URI in a visually obvious clickable/tappable element (e.g. a button), it should include text and download links for compatible XMPP clients. + +If it is possible for a particular platform's download links to automatically relay the `xmpp:` URI to the installed app, that should be implemented. See for example [Google Play Install Referrer](https://developer.android.com/google/play/installreferrer/). + +If possible, platform detection should be used to highlight download links relevant to the user's current platform. + +If the detected platform is a desktop environment, consider also adding a QR code for easy transmission to a user's mobile device. + +[XEP-0401]: /extensions/xep-0401.html "Ad-hoc Account Invitation Generation" +[XEP-0445]: /extensions/xep-0445.html "Pre-Authenticated In-Band Registration" +[XEP-0379]: /extensions/xep-0379.html "Pre-Authenticated Roster Subscription" diff --git a/content/implementation-guidelines/protocol.md b/content/implementation-guidelines/protocol.md new file mode 100644 index 000000000..bdb30a29a --- /dev/null +++ b/content/implementation-guidelines/protocol.md @@ -0,0 +1,372 @@ +--- +Title: XMPP Protocol Guidelines +layout: single-implementation-guidelines +--- + +## Overview + +The XSF has published [over 400 XEPs](/extensions/) over many years. However as technology, +user expectations and best practices evolve, the protocol too is always evolving. + +This leads to confusion about which set of XEPs are "current", which are required +only for backwards-compatibility, and which serve only to document experimental +protocols that never made it off the drawing board. + +Instead of focusing on XEP numbers, this document simply focuses on the different +areas of functionality, and describes the currently-recommended XEPs that should be +used to implement each. + +Notes are provided to provide context about past and future versions of the protocol, +which may be helpful for backwards-compatibility or planning future development. + +### Target audience + +The protocols discussed here should be implemented in reusable libraries. Client developers +may use this document to assist them in choosing an XMPP library, or submitting feature +requests or contributions to their library of choice. + +Reusing libraries whenever possible reduces fragmentation and duplicated effort. + +## Core + +### Service discovery + +One of the unique features of XMPP is its ability to support a diverse range of software +on a single network, yet always allow basic functionality to work. + +Either due to the ongoing evolution of technology, or due to constrained environments (e.g. IoT) +or usage restrictions (e.g. accessibility), different XMPP software may support different +sets of features on top of the core messaging and presence functionality described in the +RFCs. + +It is often useful to know what features a remote entity supports before performing some operation. +For example when deciding whether to send formatted messages, or determining the best available +method of transferring a file. + +- [XEP-0030](/extensions/xep-0030.html) is the basic mechanism for advertising and discovering features +- [XEP-0115](/extensions/xep-0115.html) is a strongly recommended extension that allows caching of these features + +#### Notes + +[XEP-0115](/extensions/xep-0115.html) may be revised or replaced at some point in the future, such as by [XEP-0390](/extensions/xep-0390.html), to allow +hash agility and making the algorithm more robust to cache poisoning attacks. + +### Resource generation + +The client should generate a unique random identifier per device or client instance. The +identifier should be reused between sessions, and should not reveal any information +about the user, their device, or their location. + +## Messaging + +This section covers some protocols that are useful for general messaging. + +### Formatting + +The current recommendation is that developers may simply implement the rules in [XEP-0393](/extensions/xep-0393.html) for +formatting message bodies that they receive. + +#### XHTML-IM deprecation + +A previous formatting specification defined in [XEP-0071](/extensions/xep-0071.html) has been deprecated. Many implementations +failed to properly sanitize the formatted payload (it's tricky), leading to security issues +(particularly in web applications). + +Implementation of [XEP-0071](/extensions/xep-0071.html) is not encouraged, but if formatting is a strong requirement along with +backwards compatibility (many clients still implement it currently), it remains an option if careful +attention is given to sanitizing the XHTML before display. Consider using [xhtml-im.js](https://github.com/zeen/xhtml-im.js) in a web client, or as a reference. + +## Multi-device + +XMPP was ahead of its time in supporting multiple devices connected to a single account - although +interestingly even today some popular messaging systems are still limited to a single device, +typically mobile, even when many people have a mobile, tablet and laptop or desktop. + +Historically XMPP aimed to determine which device the user most likely wanted to receive messages +on - it did this using a 'priority' mechanism in presence. Over time bandwidth and CPU costs, +as well as user expectations, have shifted. Today most people want an "everything everywhere" +approach to messaging, where all their devices are in sync. + +Modern XMPP clients should not set a priority in their presence, and they should implement the +following XEPs: + +- [XEP-0280](/extensions/xep-0280.html): Message Carbons - for "live" synchronization of conversations between online devices +- [XEP-0313](/extensions/xep-0313.html): Message Archive Management - for "catch-up" of messages that were exchanged while a device was offline + +### Known issues + +There are currently some minor open issues regarding these protocols that developers should be aware of. + +#### Race during login + +There is a race condition during login between Carbons and MAM. If you synchronize with the archive first, +you may miss some messages sent to other devices before you enable Carbons. + +If you enable Carbons first, you may receive duplicates from the archive of messages you already received. + +The current best solution is to enable Carbons, perform the query, and de-duplicate any received messages +before presentation to the user. + +This issue will be solved in the future through [XEP-0386](/extensions/xep-0386.html) or an alternative atomic "fetch and subscribe" +command. + +#### IDs of outgoing messages + +When a client sends a message, it is not currently possible for it to discover the ID that the +server assigned to the message in the archive. This means that it is unable to use them as synchronization +points and therefore it may receive its last outgoing message(s) when performing an archive sync. + +Example: + +1. Client receives message A, and records the ID so it can use +2. Client sends message B, but the ID is not known to the client +3. Client goes offline +4. Client comes online, and tries to sync with archive. Last known ID was of message A, so it synchronizes from that point +5. Server responds to the sync with message B, and all subsequent messages. + +Solving this issue may happen through an extension of Carbons (to reflect sent messages back to the sender +with the ID added and any other additional info), or through a new MAM subscription protocol. + +## Mobile + +There are some special considerations that mobile clients can make to increase battery life and reduce +data consumption. + +- [XEP-0286](/extensions/xep-0286.html) - informational XEP providing advice to mobile developers on efficient data usage +- [XEP-0352](/extensions/xep-0352.html) - used to inform the server of whether the client is currently active/focused (which allows +the server to prioritize traffic) + +## Reliability + +In the real world, it is normal for clients to get briefly disconnected. These extensions deal with +ensuring reliable message delivery and reporting. + +- [XEP-0184](/extensions/xep-0184.html) - end-to-end acknowledgement, i.e. the recipient has successfully received the message +- [XEP-0198](/extensions/xep-0198.html) - hop-to-hop acknowledgement, and allows efficient resume of broken connections without data loss + +## Read state synchronization + +[Multi-device][#multi-device] support is all well and good but one thing +that further improves the experience is not having to dismiss +notifications and unread counters for messages that have already been +read on another device. + +- [XEP-0280](/extensions/xep-0280.html): Carbon copies + of replies, implying that prior messages have been read. +- [XEP-0333](/extensions/xep-0333.html): Chat Markers - + to signal that messages have been shown to the user. + +### Notifications + +Avoid notifications while activity from another client is detected via +Carbons. Combine with Chat Marker tracking to determine whether to +notify after activity ceases, with some timeout. + +## File transfer + +Transferring a file from A to B is surprisingly a non-trivial problem for the internet, it seems. + +A number of approaches have been tried in XMPP. They are documented here, and fall into two categories: +peer-to-peer and server-mediated. + +It is strongly recommended for clients to implement HTTP upload to provide the best user experience. +The other mechanisms are optional (the advantages of implementing each one are documented in the +relevant section). + +There are three file transfer methods that a modern XMPP client may implement: + +- HTTP upload (required) +- Jingle streams (recommended for large file support) +- Stream initiation (deprecated, but may be implemented for backwards-compatibility) + +### HTTP upload + +**Required:** *yes* + +The newest file transfer mechanism available, described in [XEP-0363](/extensions/xep-0363.html). It is strongly recommended to +implement this mechanism to provide the best user experience. + +#### Benefits + +- Does not depend on the recipient supporting it (simply falls back to sending a URL) +- Works with group chats +- Works when the recipient is offline +- Allows the recipient to receive on multiple devices + +#### Disadvantages + +- Unsuitable for large files (server determines what the size limit is, and may enforce usage quotas) +- Does not support streaming (file must be entirely uploaded to the server before recipient can begin to receive it) +- Requires server support + +#### Communicating the URL + +After uploading the file successfully, the sender should communicate the URL to the recipient by sending a +`` stanza with the "Get URL" provided by the server in the `` of the message. + +Additionally the sender should include a [`jabber:x:oob`](/extensions/xep-0066.html#x-oob) +element in the message stanza with the same URL. + +{{< info-block type="note" >}} +To enable automatic display of media in the conversation view, Conversations (at least) currently requires that the `` contain *just* the URL, and it must be identical to the URL in the `jabber:x:oob` payload. +The `` element is not used or supported by Conversations. +This behavior means that it is not possible for any text to directly accompany a media file, and must be sent separately. +{{< /info-block >}} + +### Jingle + +**Required:** *optional - used for large file support* + +Jingle is a generic framework that allows clients to negotiate a direct stream between themselves, which can +be used to transfer files (it is also used for voice/video and other p2p applications based on XMPP). It was +originally developed at Google and contributed to the XSF where it evolved into today's standard. + +Because it is a generic framework that supports different underlying transports and different media types, +Jingle is split into multiple XEPs. For file transfer the following are relevant: + +- [XEP-0166](/extensions/xep-0166.html) - the core Jingle framework +- [XEP-0234](/extensions/xep-0234.html) - the Jingle file transfer definition +- [XEP-0260](/extensions/xep-0260.html) - the most common transport mechanism for files (SOCKS5 Bytestreams - may be directly peer-to-peer or server-mediated) +- [XEP-0261](/extensions/xep-0261.html) - a fallback transport for tunneling the data directly over the XMPP stream (inefficient and slow, but always succeeds) + +#### Advantages + +- Supports streaming (recipient receives at the same time as the sender sends) +- Allows code re-use if the client also implements Jingle for audio/video streams +- No server-side storage required, and the data will pass directly between clients if firewalls/network conditions allow, which makes it suitable for larger files. + +#### Disadvantages + +- Because it is a multi-purpose framework it can be complex. +- Not all clients support it. +- In the case of the recipient having multiple devices, only a single one can receive the file. +- Does not work for sharing a file with multiple people (e.g. in a group chat) +- Only works if the recipient is online + +{{< info-block type="note" >}} +Although it is the only recommended negotiation protocol for peer-to-peer streams today, note that Jingle support is not nearly universal even among modern clients. +{{< /info-block >}} + +### Stream Initiation (pre-Jingle) + +**Required:** *no - optionally implement for sending large files to pre-Jingle clients* + +[XEP-0096](/extensions/xep-0096.html) describes the stream negotiation protocol that was used before Jingle. It is widely supported, and can use the same +transports: + +- [XEP-0065](/extensions/xep-0065.html) +- [XEP-0047](/extensions/xep-0047.html) + +It is not recommended to implement this mechanism in new clients, except for compatibility with older clients +is required (and HTTP Upload does not suffice for some reason). + +#### Advantages + +- Supports streaming (recipient receives at the same time as the sender sends) +- Widely supported in older clients + +#### Disadvantages + +- Deprecated. Modern clients are switching to Jingle negotiation. +- In the case of the recipient having multiple devices, only a single one can receive the file. +- Does not work for sharing a file with multiple people (e.g. in a group chat) +- Only works if the recipient is online + +## User Profiles + +- [XEP-0163](/extensions/xep-0163.html) is the base publishing method. +- [XEP-0222](/extensions/xep-0222.html) for access controls. +- [XEP-0084](/extensions/xep-0084.html) for profile picture. +- [XEP-0172](/extensions/xep-0172.html) for nickname. +- [XEP-0292](/extensions/xep-0292.html) for extended details (optional). + +Simpler clients may choose to only use XEP-0084 and XEP-0172 to provide a limited user profile, +while more advanced clients could publish more details via XEP-0292. + +### Avatars + +- **Do** publish avatars via XEP-0084. +- **Do not** publish avatars via XEP-0292. + +#### Format and size considerations + +Use widely supported format such as PNG or JPEG. + +The avatar must fit within stanza size restrictions, after being base64-encoded and wrapped in +protocol. Recommended to keep the avatar no larger than 72 KiB which would keep resulting stanzas +under 100 KiB. + +### Access control + +Data published via [XEP-0163](/extensions/xep-0163.html) would by default be +available only to the user's contacts. Historically, profiles published via the legacy +[XEP-0054](/extensions/xep-0054.html) method were public. + +Modern PEP implementations should implement for 'access model' as described by +[XEP-0222](/extensions/xep-0222.html), and allow users to share or limit their +personal details as they choose. + +Access model for both XEP-0084 nodes and the XEP-0172 node should be kept the same. + +Access to the full XEP-0292 profile, if supported, may be configured separately or via a tri-state +such as: + +- Everything contacts only +- Public picture and nickname, private profile +- Everything public + +### Legacy + +- [XEP-0054](/extensions/xep-0054.html) is the legacy profile publishing method. +- [XEP-0153](/extensions/xep-0153.html) notifies contacts about avatar changes. +- [XEP-0398](/extensions/xep-0398.html) tells you whether you can ignore that and let the server do it for you. + +## Group chat + +See [Group Chat](/implementation-guidelines/groupchat). + +## Contact management + +### Blocking + +- [XEP-0191](/extensions/xep-0191.html) for blocking communication with a list of other JIDs + +## Encryption + +All XMPP streams must be encrypted using TLS as specified in RFC 6920. + +Clients may additionally support encrypting messages within the XMPP +stream. This can prevent untrusted servers from viewing or modifying +the contents of exchanged messages, and is known as 'end-to-end +encryption'. + +The current preferred protocol for this in XMPP is OMEMO, specified +in [XEP-0384](/extensions/xep-0384.html). Client support is indicated at [omemo.top](https://omemo.top/). + +### Notes + +#### OTR + +Prior to OMEMO, many clients implemented the protocol-agnostic +encryption protocol "OTR". + +Although it sufficed for simple use cases (sender and recipient have +a single device connected, and both support OTR), it has a number of +drawbacks when used within XMPP. Traditionally it has not supported multiple devices +very well, nor group chats, and it only protects the message body. + +These issues lead to a poor user experience. + +Modern XMPP clients that implement OTR must add a [XEP-0380](/extensions/xep-0380.html) tag to their outgoing +messages. + +#### MLS + +The IETF is currently working on standardizing a new protocol for +['Message Layer Security'](https://datatracker.ietf.org/wg/mls/about/) +with support from a number of prominent members of the online communications +space. It is hopeful that it may one day allow messaging applications +of all protocols to share code and crypto reviewed by experts. + +However this work is in its early days, and OMEMO is expected to be +the recommended approach for some time to come. diff --git a/content/implementation-guidelines/rationale.md b/content/implementation-guidelines/rationale.md new file mode 100644 index 000000000..3b3d689ba --- /dev/null +++ b/content/implementation-guidelines/rationale.md @@ -0,0 +1,108 @@ +--- +Title: Rationale +layout: single-implementation-guidelines +--- + +This page gives additional insight into why some of the recommendations +in the Modern XMPP documentation are made. + +## Group chats + +Discussion about the UI/UX issues around group chats initially happened +at the first [UX sprint](/implementation-guidelines/2019-01-brussels.md). Some observations +were made: + +* MUC configuration is messy, for users and developers +* Most MUCs fall roughly into a couple of standard configurations + +### Types of groups + +Software is about people. Good UX design is about understanding how +people use the software. + +Group communication is a well-studied area of human interaction in +general[^wp-group-dynamics]. It has been noted by researchers that +groups can fall into four different types[^wp-group-types]. + +Of the four group types, two are formed of people that share a personal +or social connection (the so-called 'Primary' and 'Social' groups). Examples +include families, groups of friends, colleagues or clubs. + +The other two group types ('Collective' and 'Category') are formed from +people who share common traits, goals or interests. Such groups tend +to be larger, less sticky, lack concrete social bonds and thus be more +open. + +The developers of the Fractal IM client noted[^banquets-bbqs] the struggle +they faced trying to design an ideal UI for chats in their Matrix client. +They observed the two high-level categories which they termed "Barbecue" +(small, social-focused, closed, trusted) and "Banquet" (large, +topic-focused, open, untrusted). + +The Fractal developers went as far to consider two completely separate +applications to cater for the two types of discussions. + +Many other modern messaging apps contain both types of group chat, but +unlike most XMPP clients, they *do* distinguish them visually. + +From a protocol perspective this distinction is unnatural - XMPP, like +similar open chat protocols such as IRC and Matrix cares little for how +the group is used, and provides various fine-grained configuration options. +Other than minor configuration tweaks there is little to distinguish the +two use-cases at a technical level. + +However dividing these up at the UI level provides a number of advantages: + +* Removes/reduces the need for fine-grained configuration options that users + may not understand, or misuse +* Helps prevent user confusion when sharing content (it is harder to + accidentally share family photos with an open-source project's chatroom + full of strangers, if the family group and project group are strongly + separated) +* Makes managing notification rules easier + +#### Terminology + +It was agreed that "room" terminology is outdated[^trend-chat-room], and not used by +any modern messaging systems. This deprecates "chat room", "occupant", "entering", +"leaving" and all room-related terminology. + +Most applications these days use the terms "Chat" (Messenger), "Group" (WhatsApp, Signal) +or "Channel" (Slack, Discord, IRC). + +Primary options are: + +- "Chat" + - Too ambiguous - clients may want to visually separate one-to-one chats + from other kinds of chats, but if the term "Chats" is used for all of them, + this is hard +- "Group" or "Group Chat" + - Widely understood due to its use in all the most popular messaging apps + - Even for those unfamiliar with such apps, "group" is a natural term for + multiple people communicating together. + - Still ambiguous regarding whether the chat is of the private or public kind + (see above for the rationale on why these are fundamentally different, and should + be displayed and treated differently). If public and private chats are handled + so differently, they should have different names. + - "Group" is already a term used by the roster, may be confusing +- "Private Group Chat" and "Public Group Chat" + - Too wordy, ambiguous without the modifier (Public/Private), and perhaps doesn't + adequately capture the differences between public/private chats. +- "Channel" + - Successfully used by existing large platforms (mostly those focused primarily on + group chats: Slack, Discord, IRC). + - Used by Telegram to mean something different: a one-way broadcast from one user to many + - Significantly different from 'Group Chat', no chance of confusion + - Unfamiliar to people who haven't already used other communication tools that use + this term + - However, not a hard concept to grasp + - Difficult to translate to other languages - literal translations such as "Kanal" (de) + don't necessarily make sense. + + + +[^wp-group-dynamics]: https://en.wikipedia.org/wiki/Group_dynamics +[^wp-group-types]: https://en.wikipedia.org/wiki/Group_dynamics#Types_of_groups +[^banquets-bbqs]: https://blogs.gnome.org/tbernard/2018/05/16/banquets-and-barbecues/ +[^trend-chat-room]: Google Trends notes a significant decline since + [at least 2004](https://trends.google.com/trends/explore?date=all&q=chat%20room). diff --git a/content/implementation-guidelines/sync.md b/content/implementation-guidelines/sync.md new file mode 100644 index 000000000..728725eb4 --- /dev/null +++ b/content/implementation-guidelines/sync.md @@ -0,0 +1,57 @@ +--- +Title: Syncing Message History +layout: single-implementation-guidelines +--- + +## MAM Strategies + +Fetching history from the server is accomplished with [Message Archive +Management][MAM] (MAM). +New XMPP clients frequently use naïve methods of querying history that result in +long wait times for history, or frozen UIs. +However, a robust strategy for fetching history has not been previously +documented. +This section documents strategies used by clients in the wild, as well as +implementation recommendations for MAM. + +### Requirements + +- Allow the user to send a message in response to history fetched from the + server as quickly as possible +- Do not generate dozens of notifications for old messages + +### Implementation Notes + +- Don't treat history like normal incoming messages. + If querying lots of messages, aggregate and commit them to the data store + (assuming a transactional database) as a group. + Do the same for updating the UI and displaying notifications (ie. display one + notification, not dozens or perhaps hundreds as messages come in). +- Look up the last message _in your datastore before_ sending initial presence, + otherwise you may receive a message before you get the last ID and end up with + a gap. +- If using paging, committing one page at a time to the DB/UI is a natural way + to break up large transactions and provide the user with quicker feeling + updates. +- If `mam:2#extended` is supported, query using `after-id` and `before-id` and + fall back to using the time of the last or earliest message (`start` and + `end`) if not. + +### Communiqué + +- On client start iterate through all items in the roster + - If no messages exist in the local archive: + - Query in reverse order (in case the server breaks it up by page and we + end up committing pages separately) with `end: now && limit: X` (where + X is some configurable number or a guess at a page number based on + screen size, etc.) + - Else: + - Query with `after-id: ` or `start: ` + (making sure that the last message was pulled from the DB before we + send initial presence) +- If the user scrolls to the top: + - Query in reverse order with `before-id: && limit: X` or + `end: && limit: X` + + +[MAM]: /extensions/xep-0313.html diff --git a/content/implementation-guidelines/terminology.md b/content/implementation-guidelines/terminology.md new file mode 100644 index 000000000..ac995fd8b --- /dev/null +++ b/content/implementation-guidelines/terminology.md @@ -0,0 +1,45 @@ +--- +Title: Terminology +layout: single-implementation-guidelines +--- + +To reduce user confusion when switching between clients, it is good to use only recommended +terms. + +| Historic/protocol terms | Recommended user-facing terms | +|----------------------------------|----------------------------------------------------------------------| +| MUC, Room, Chatroom, Conference | *Group chat* or *Channel*[^rationale-gc] (see [Multi-user Chats][]) | +| Occupant | *Participant* | +| JID | *Address* or *XMPP address* | +| Roster | *Contact list* | +| Avatar | *Profile picture* | + +**Note:** The recommendations only apply to user-facing text, such as application UIs and other content directed towards end users. There is no intent to change the language used by developers for discussing protocol elements[^rationale-dev-terms]. This is why you will still see terms such as "JID" used across the developer-oriented documentation of this project, for example. + +## Translation + +Most XMPP Clients are distributed in multiple languages. In the process of translating a client, people with various backgrounds (not necessarily XMPP-related) are contributing translations. +This table of terms (German, French and Spanish to begin with) aims to be a reference for recommended translations in the future. + +At the moment, this table intends to support discussing the translation of key terms. [Discuss with us!](xmpp:modernxmpp@rooms.modernxmpp.org?join) + +| English term | German | French | Spanish | Portuguese | Japanese | +|-------------------------|----------------|-------------------|--------------------|--------------------|------------------| +| Group chat | Gruppenchat | Groupe | Grupo de chat | Grupo de conversa | グループチャット | +| Channel | Channel | Salon | Canal | Canal | チャンネル | +| Participant | Teilnehmer | Participant | Participantes | Participantes | 参加者 | +| Address or XMPP address | XMPP-Adresse | Adresse XMPP | Dirección XMPP | Endereço XMPP | XMPPアドレス | +| Contact list | Kontaktliste | Liste de contacts | Lista de contactos | Lista de contactos | 連絡帳 | +| Profile picture | Profilbild | | | | プロフィーロ写真 | + +You’ll find more terms in the [term overview](/implementation-guidelines/translation-discussion). + +[Add a language...](https://github.com/modernxmpp/modernxmpp) + + + +[^rationale-gc]: Rationale [group chat terminology](/implementation-guidelines/rationale#terminology) + +[Multi-user Chats]: /implementation-guidelines/groupchat + +[^rationale-dev-terms]: General agreement is that this would only cause confusion, for little gain. See e.g. discussion at https://github.com/modernxmpp/modernxmpp/pull/23 diff --git a/content/implementation-guidelines/translation-discussion.md b/content/implementation-guidelines/translation-discussion.md new file mode 100644 index 000000000..0c549d682 --- /dev/null +++ b/content/implementation-guidelines/translation-discussion.md @@ -0,0 +1,86 @@ +--- +Title: Translation discussion +layout: single-implementation-guidelines +--- + +Most XMPP clients are distributed in multiple languages. In the process of translating a client, people with various backgrounds (not necessarily XMPP-related) are contributing translations. + +The following tables are gathering the various translations of key terms in (a limited set of) clients to give an overview about what is currently used. This document intends to serve as a basis to discuss recommendations for key term translations. + +## Translation services used by clients + +Client | Service +--------------|------------------------------------------------------------------- +Conversations | [Weblate](https://translate.codeberg.org/projects/conversations/) +converse.js | [Weblate](https://hosted.weblate.org/projects/conversejs/) +Dino | [Weblate](https://hosted.weblate.org/projects/dino/) +Monal | [Weblate](https://hosted.weblate.org/projects/monal/) +Gajim | [Weblate](https://translate.gajim.org/) +PSI(+) | [Transifex](https://www.transifex.com/tehnick/psi-plus/) +Swift | [swift.im git](https://swift.im/git/swift/tree/Swift/Translations) +yaxim | [launchpad.net](https://translations.launchpad.net/yaxim/master) + +## German + +### Terms currently used in clients (German) + +| Term \ Client | Conversations | Converse.js | Dino | Gajim | PSI(+) | Swift.im | yaxim | +|----------------------|-------------------------------|-------------------------------|------------------------|---------------------------|------------------------------|---------------------|-----------------------------------| +| XMPP address | XMPP-Adresse | XMPP-Adresse | JID | XMPP-Adresse | JID | JID, Jabber-ID | JID | +| contact list | Kontaktliste | Kontakte | Kontaktliste | Kontaktliste | Kontaktliste | Kontaktliste | Liste? | +| bookmarks | Lesezeichen | Lesezeichen | - | Gespeicherte Gruppenchats | Lesezeichen | Lesezeichen | - | +| auto join | Auto-Join-Funktion | automatisch beitreten | - | automatisch beitreten | automatisch beitreten | - | - | +| channel | Channel | Gruppenchat, Raum | Kanal/Konferenz | Gruppenchat | Gruppenchat, Chatraum | Chatraum | Gruppenchat | +| group chat | Gruppenchat | Gruppenchat | Raum | Gruppenchat | Gruppenchat, Chatraum | Chatraum | Gruppenchat | +| role | ? | Rechte, Rolle | - | Rolle | Rolle, Funktion | Rolle | - | +| moderator | Moderator | Moderator | - | Moderator | Moderator | Moderator | - | +| participant | Teilnehmer | Teilnehmer | members ? | Teilnehmer | Teilnehmer | Teilnehmer | Teilnehmer | +| kick | ausschließen? | hinauswerfen | hinauswerfen | rauswerfen | rauswerfen | rausschmeißen | kick | +| ban | ausschließen | entfernen | - | sperren | verbannen | verbannen | ban | +| affiliation | Rechte? | Zugehörigkeit | - | Gruppenzugehörigkeit | Mitgliedschaft, Angliederung | Zugehörigkeit | - | +| owner | Eigentümer | Eigentümer | Eigentümer | Eigentümer | Besitzer | Besitzer | - | +| admin | Administrator | Admin | Administrator | Administrator | Administrator | Administrator | - | +| member | Mitglied | Mitglied | Mitglied | Mitglied | Mitglied | Mitglied | - | +| user | - | Besucher | Gast | - | - | - | - | +| nickname | Nickname | Spitzname, Nickname | Spitzname | Spitzname | Spitzname | Spitzname, Nickname | Nickname | +| history | Verlauf | - | Gesprächsverlauf | Unterhaltungsverlauf | Nachrichtenchronik | Verlauf | Chatverlauf, Unterhaltungsverlauf | +| fingerprint | Fingerabdruck | Fingerabdruck | Fingerabdruck | Fingerabdruck | Fingerabdruck | - | - | +| subscription request | Online-Status anfragen | Kontaktanfrage[^sub-converse] | Kontaktanfrage | Kontaktanfrage | Anfrage | Anfrage | Abonnementanfrage | +| subscription | Online-Status | Anwesenheitsabonnement | - | Abonnement | Abonnement | Abonnement | - | +| chat | Unterhaltung | Chat | Unterhaltung | Chat | Chat | Chat | (Unterhaltung) | +| read receipts | Lese- und Empfangsbestätigung | - | Lesebestätigungen | Empfangsbestätigungen | Übermittlungsbestätigung | Empfangsbestätigung | - | +| typing notifications | Tipp-Benachrichtigung | - | Tippbenachrichtigungen | Chatstatus | Tipp-Benachrichtigung | - | - | +| avatar | Profilbild | Avatarbild | Profilbild | Kontaktbild | Avatar | Bild | - | + +### Recommended translation + +Term | Translation +-------------|------------ +XMPP address | +contact list | +bookmarks | +auto join | +... | + +## French + +### Terms currently used in clients (French) + +| Term \ Client | Conversations | Converse.js | Dino | Gajim | PSI(+) | Swift.im | yaxim | +|---------------|------------------------|-------------|--------|-----------------------|---------|-----------|--------| +| channel | Canal | Salon | Salon | Salon (de discussion) | | Salon | Salon | +| group chat | Conversation de groupe | Salon | Salon | Salon (de discussion) | | Salon | Salon | + +### Notes for french translations (from pep.) + +English | French +-------------|----------------------- +group chat | groupe (de discussion) +channel | salon (de discussion) +participant | participant +XMPP address | Adresse XMPP +contact list | Liste de contact + + + +[^sub-converse]: Subscription requests in converse.js are called contact requests diff --git a/themes/xmpp.org/assets/css/style.css b/themes/xmpp.org/assets/css/style.css index 2ec977f13..5b715d804 100644 --- a/themes/xmpp.org/assets/css/style.css +++ b/themes/xmpp.org/assets/css/style.css @@ -435,6 +435,23 @@ button[name="show-xep-implementations"] { text-align: center; } +.docs-container { + background-color: #f8f9fa; +} +.docs-container p, li { + font-family: unset !important; + font-size: 1rem; + line-height: 1.5; + color: #212529; +} + +code { + padding: 0.2em 0.4em; + margin: 0; + font-size: 85%; + background-color: rgba(27, 31, 35, 0.05); + border-radius: 0.275rem; +} /* Dark theme */ @media (prefers-color-scheme: dark) { @@ -514,4 +531,14 @@ button[name="show-xep-implementations"] { .mermaid { background-color: #6e7882; } + + .docs-container { + background-color: #2f3337; + } + .docs-container p, li { + color: #dddddd + } + code { + background-color: rgba(215, 215, 215, 0.05); + } } diff --git a/themes/xmpp.org/layouts/_default/single-implementation-guidelines.html b/themes/xmpp.org/layouts/_default/single-implementation-guidelines.html new file mode 100644 index 000000000..06ab90848 --- /dev/null +++ b/themes/xmpp.org/layouts/_default/single-implementation-guidelines.html @@ -0,0 +1,23 @@ +{{- define "main" -}} +
+
+
+
+
+

{{- .Title -}}

+ {{- partial "page_meta.html" . -}} +
+
+
+ {{- .Content -}} +
+
+
+
+ {{- $currentSection := .Section -}} + {{- if $currentSection -}} + {{- partial "sidebar_implementation_guidelines.html" . -}} + {{- end -}} +
+
+{{- end -}} diff --git a/themes/xmpp.org/layouts/partials/sidebar_implementation_guidelines.html b/themes/xmpp.org/layouts/partials/sidebar_implementation_guidelines.html new file mode 100644 index 000000000..5a1e00ba9 --- /dev/null +++ b/themes/xmpp.org/layouts/partials/sidebar_implementation_guidelines.html @@ -0,0 +1,26 @@ +