diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 36c08b37..eb25b5e3 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -32,6 +32,8 @@ Ewan Fosstodon Gobuntu gvfs +homeserver +homeservers Indri IPs ISOs @@ -47,6 +49,7 @@ metapackage microreleases MIRs misconfigured +Mjolnir MOTUs multiarch Mythbuntu diff --git a/docs/community/contributors/matrix/completing-setup.md b/docs/community/contributors/matrix/completing-setup.md new file mode 100644 index 00000000..e3166003 --- /dev/null +++ b/docs/community/contributors/matrix/completing-setup.md @@ -0,0 +1,51 @@ +(matrix-completing-setup)= +# Completing your Matrix setup + +If you are reading this guide, you most likely completed the {ref}`Getting started with Matrix ` guide. +This document explains the next steps to complete your Matrix setup. +While these steps are not required, they are greatly recommended because they will make your long-term experience a lot better. + + +## Backup your encryption keys + +Make sure your encryption keys are backed up. +Without encryption key backups, you might not be able to restore your end-to-end encrypted chats if you log off all your devices. + + +### Recovery key + +* Open your Element client, click the "gear" icon, and select {guilabel}`All settings` +* Select the {guilabel}`Encryption` icon +* Navigate to the {guilabel}`Recovery` section and select {guilabel}`Set up recovery` +* Follow the on-screen instructions to generate your unique security key +* Store your unique security key in a safe place +* Ensure the button in the {guilabel}`Recovery` section now reads: "Change recovery key" + + +### Export keys + +Optionally, you can also manually export your encryption keys: + +* Navigate to the {guilabel}`Advanced` section of the {guilabel}`Encryption` settings +* Select {guilabel}`Export keys` +* Read the instructions carefully, and enter a passphrase to protect your manual encryption keys +* Download the export file and store it in a safe place + + +## Advertise your Matrix ID + +To make sure people know how to reach you, it's best to advertise your Matrix ID in a prominent place. +Launchpad now has the option to advertise your Matrix ID on your profile. +Edit it on [Launchpad](https://launchpad.net/~/). + +![Matrix ID|256x88](matrix-id.png) + +Make sure to always write the full matrix ID, including the homeserver, in the form `@:`. Just specifying your username is not enough, because different people can have the same username on different homeservers. + + +## Further reading + +* Do you have multiple Matrix accounts and want to use them at the same time? {ref}`matrix-multiple-accounts` +* Do you want to create rooms for your own community? {ref}`matrix-management` +* Do you want to know who is in charge of moderation and policy-making on our homeserver? {ref}`matrix-council` + diff --git a/docs/community/contributors/matrix/continue-with-saml.png b/docs/community/contributors/matrix/continue-with-saml.png new file mode 100644 index 00000000..703a0d2b Binary files /dev/null and b/docs/community/contributors/matrix/continue-with-saml.png differ diff --git a/docs/community/contributors/matrix/index.md b/docs/community/contributors/matrix/index.md new file mode 100644 index 00000000..bcd3cf20 --- /dev/null +++ b/docs/community/contributors/matrix/index.md @@ -0,0 +1,33 @@ +(using-matrix)= +# Using Matrix + +Matrix is the platform we use to chat and discuss various topics within the Ubuntu Community. + + +## Getting started + +In this section, we'll show you how to join our Matrix community from the federated Matrix network, and how to log in directly on the Ubuntu homeserver. + +```{toctree} +:maxdepth: 1 + +onboarding +completing-setup +register-ubuntu-com +multiple-accounts +``` + + +## Reporting issues + +In this section, you'll find guides to reporting both bugs and spammers. + +```{toctree} +:maxdepth: 1 + +matrix-bug-reporting +matrix-spam +matrix-abuse-reporting +matrix-ignore-list +``` + diff --git a/docs/community/contributors/matrix/matrix-abuse-reporting.md b/docs/community/contributors/matrix/matrix-abuse-reporting.md new file mode 100644 index 00000000..3b5a0f04 --- /dev/null +++ b/docs/community/contributors/matrix/matrix-abuse-reporting.md @@ -0,0 +1,47 @@ +(matrix-abuse-reporting)= +# How to report abuse + + +(defenders-contact)= +## Ask for Defender help + +Matrix users that see offensive, inappropriate, or {ref}`CoC-violating ` content, can help the Operations team by reporting it. +Defenders can help with this type of task and they can protect all official Ubuntu rooms. +If you need a Defender: + +* Join the Ubuntu {matrix}`Matrix Ops room ` + +* Send a message in this room asking Defender's help and pointing to the room where action needs to be taken, for example: `!defenders please help in room #discuss:ubuntu.com` + +Adding `!defenders` before your message triggers a notification to all the Defenders in the Ubuntu homeserver and can be used in any room. + + +(moderators-contact)= +## Ask for moderation help and advice + +When a Matrix user witnesses behavior that is not obvious spam, inappropriate, or breaching the CoC, a moderator might be needed. +Moderators observe situations, de-escalate when possible, and intervene when necessary. +If you need the help of a Moderator: + +* Click on the name of the room from the top bar of your Element client. +* From the dropdown, select {guilabel}`People` and click on it. +* A panel will open on the right side of your Element client, with a list of users. +* Look for users that have "Mod" next to their name. If you see none, you can reach out to users that have "Admin" next to their name. +* Select the moderator or administrator you want to contact, and click on the user name. +* The panel changes to the particular user; from {guilabel}`Options`, select "Message". + + +## Contact the Matrix Council + +If you need to escalate an issue or reach out to the Matrix Council, refer to {ref}`contact-matrix-council`. + + +## Further reading + +To learn more about moderation and Matrix in general: + +* {ref}`How to manage your ignore list ` +* {ref}`matrix-moderation-and-defense` +* {ref}`matrix-defenders` +* {ref}`using-matrix` + diff --git a/docs/community/contributors/matrix/matrix-bug-reporting.md b/docs/community/contributors/matrix/matrix-bug-reporting.md new file mode 100644 index 00000000..52a5c6f4 --- /dev/null +++ b/docs/community/contributors/matrix/matrix-bug-reporting.md @@ -0,0 +1,14 @@ +(matrix-bug-reporting)= +# Matrix bug reporting + +Bug reports and feature requests +: Report bugs, issues, and feature requests in [this GitHub repository](https://github.com/canonical/synapse-operator/issues). We will review the feedback regularly and use it to resolve issues or consider features to improve interactions between community members and staff. + + +Matrix discussions +: If you want to take part in the broader discussion about the Ubuntu Matrix project, you can do so in [this Discourse thread](https://discourse.ubuntu.com/t/modern-communication-platforms-call-for-feedback/36763/), or in the {matrix}`matrix-ops` Matrix Ops room. This is where you can discuss issues or bugs, and where you can discuss the Ubuntu Matrix project in general. + + +Known issues +: The Element web client is not available on the Ubuntu Matrix instance yet. We will send updates once the Element web client is ready to test. You can use `app.element.io` or a Desktop client as noted in the instructions. + diff --git a/docs/community/contributors/matrix/matrix-id.png b/docs/community/contributors/matrix/matrix-id.png new file mode 100644 index 00000000..04f4b465 Binary files /dev/null and b/docs/community/contributors/matrix/matrix-id.png differ diff --git a/docs/community/contributors/matrix/matrix-ignore-list.md b/docs/community/contributors/matrix/matrix-ignore-list.md new file mode 100644 index 00000000..40bb1d1b --- /dev/null +++ b/docs/community/contributors/matrix/matrix-ignore-list.md @@ -0,0 +1,31 @@ +(matrix-ignore-list)= +# Matrix ignore list + +Matrix has an "Ignore user" feature. +This feature, when used, prevents a Matrix user from reaching you. +Please note that this only affects you, and does not block the particular user for other people in your room or Homeserver. + + +## Add a Matrix user to your ignore list + +To ignore a user: + +* Select the avatar of the user you want to ignore from a chat room + +* A side panel opens on the right side of the Element client + +* In the {guilabel}`Options` category, select {guilabel}`Ignore` + + +## Manage your ignore list + +To check your ignore list and manage the users on it: + +* Select your user avatar on the top left corner of your Element client + +* Select the option {guilabel}`Security & Privacy` + +* Scroll down to the {guilabel}`Advanced` section + +* Check the {guilabel}`Ignored Users` list + diff --git a/docs/community/contributors/matrix/matrix-spam.md b/docs/community/contributors/matrix/matrix-spam.md new file mode 100644 index 00000000..d0458c84 --- /dev/null +++ b/docs/community/contributors/matrix/matrix-spam.md @@ -0,0 +1,71 @@ +(matrix-spam)= +# Dealing with spam + +Matrix occasionally has spam waves. +Sometimes, spammers target specific communities like the Ubuntu community. +While the Ubuntu Matrix Operators work hard to block the spam before you even see it, they cannot (yet) catch everything. +However, there are a few things you can do yourself to protect yourself. + + +## Don't engage + +The most important rule is to **never engage directly with the spammers**! +Spammers are trying to get your attention. +They want you to get upset and want you to respond to them. +Ignoring them is the best response. + + +## Disable image previews + +Many Matrix clients like Element allow you to disable image previews. +Since some spammers send disturbing images, it's best to turn image previews off. +This way, you won't see these images before our moderator bot removes them. + +To turn image previews off in Element Desktop, select your profile picture in the top left corner of the app, click {guilabel}`All Settings` -> {guilabel}`Preferences`, and turn the following settings off: + +* {guilabel}`Autoplay GIFs` + +* {guilabel}`Autoplay videos` + +* {guilabel}`Show previews/thumbnails for images` + + +## Block invites from banned users + +Sometimes, spam comes in the form of rogue invites to problematic rooms. +By default, banned users can still send you invites, but Element has an experimental feature that allows you to block invites of everyone we ban. + +1. In Element Desktop, select your profile picture in the top left corner of the app, click {guilabel}`All Settings` -> {guilabel}`Labs`, and turn on {guilabel}`New ways to ignore people`. +1. Then, go to {guilabel}`Ignored users` to the section {guilabel}`Subscribed lists` and add `!fTjMjIzNKEsFlUIiru:neko.dev`. + This is a community maintained list of spammers. + + +## Ignore invites and users + +To avoid spam from rogue invites, you can also ignore the user. +By doing this, that user will not be able to send you another invite. +The method to ignore the user is different depending on which app you're using. + +* On Element Desktop and Element Web, click on the invite (but don't accept it), and click **{guilabel}`Reject & Ignore user`**. +* If you're using Element Android, or another client, you need to type **`/ignore @user:example.com`** in the message box in a room and press {guilabel}`Send`. + Make sure to change the username in this command to the user inviting you. + +You can also ignore users that you are already in a room with you by clicking on the profile picture of the user and clicking {guilabel}`Ignore`. + + +## Contact the Ubuntu Matrix Operators + +If you're targeted by spam, please let the Ubuntu Matrix Operators know in the {matrix}`Ubuntu Matrix Ops ` room. +We're constantly trying to improve our tooling to block the spam before you even see it. +We're also working with other communities on Matrix to defend against spam together. +However, if something slips through the cracks, please let us know. + +If you receive spam invites, it can help the Operators if you let us know (in the Matrix Ops room) what the full username and the room ID is of the spammers. +Certain Matrix clients such as {spellexception}`Neochat` allow you to get a room ID without entering it. +You can do that by right-clicking, choosing {guilabel}`Room Settings`, and copying the {guilabel}`Room ID`. + + +## Contact your homeserver admins + +If you're using a `matrix.org` account, you can report spam invites by sending an email to `abuse@matrix.org`. + diff --git a/docs/community/contributors/matrix/multiple-accounts.md b/docs/community/contributors/matrix/multiple-accounts.md new file mode 100644 index 00000000..3a81ea85 --- /dev/null +++ b/docs/community/contributors/matrix/multiple-accounts.md @@ -0,0 +1,41 @@ +(matrix-multiple-accounts)= +# Using multiple Matrix accounts + +The Element client does not support logging in with multiple concurrent accounts. +However, the same result can be achieved indirectly, as outlined below. + + +## Using the Element Desktop app + +1. **Install Element Desktop:** + + Install via [snap](https://snapcraft.io/element-desktop) or [deb package](https://element.io/download). + +1. **Login with your first account:** + + Start Element Desktop and log in with your first account. + This becomes the default login. + +1. **Open a second account:** + + Open a console by pressing {kbd}`Ctrl` + {kbd}`Alt` + {kbd}`T`. + + Run `element-desktop --profile ` -- this opens Element with your second account. + If you don't specify your second account, it defaults to the first account. + +You can manually start Element with the second account via the CLI, or you can create a Desktop launcher shortcut for it (instructions will vary depending on the Desktop environment you use). + + +## Using Firefox and Element Web + +Firefox has a handy feature called ["Multi Account Containers"](https://addons.mozilla.org/en-US/firefox/addon/multi-account-containers/). +Each container acts as a completely different browser with different accounts. +If you open Element Web in two different containers, you can log into two accounts at the same time. + + +## Mobile + +On mobile, the options are somewhat limited. +While you can use Element Mobile alongside apps like [SchildiChat](https://schildi.chat/) or [FluffyChat](https://fluffychat.im/), they may not fully support all the features used by the Ubuntu Community, potentially impacting your experience. +This will become better with time. + diff --git a/docs/community/contributors/matrix/onboarding.md b/docs/community/contributors/matrix/onboarding.md new file mode 100644 index 00000000..9d5448db --- /dev/null +++ b/docs/community/contributors/matrix/onboarding.md @@ -0,0 +1,57 @@ +(matrix-onboarding)= +# Getting started with Matrix + +This guide will give you more information on how to collaborate with others in the Ubuntu Community using Matrix. +Matrix is a form of real-time Internet chat, where you can talk to many other community members using Ubuntu, on topics ranging from idle chit-chat, over community improvements, to support with your Ubuntu installation. + +Though a channel might have many people in it at any one time, they might not always be at their keyboard; so if no-one responds, just wait around and someone will hopefully answer soon enough. + + +(matrix-get-a-client)= +## Get a client + +To connect to Matrix, you first need a "Client" app. +**We strongly recommend using Element** since that is the only client that supports all the features used in our community. +If you already have a Matrix client, you can continue to {ref}`matrix-get-an-account`. + +* [Element Web](https://app.element.io/) is the simplest option. + It works right inside your browser, so you don't need to install anything! + +* You can also install Element on every operating system. + On Ubuntu, you can install the [`element-desktop` snap](https://snapcraft.io/element-desktop). + For other operating systems, [download Element](https://element.io/download). + + +(matrix-get-an-account)= +## Get an account + +To participate in the conversation, you need to create a Matrix account. +If you already have one, then you can continue to {ref}`matrix-join-the-ubuntu-space`. + +* Regular community members who need a new Matrix account can [register at `matrix.org`](https://matrix.org/docs/chat_basics/matrix-for-im/#creating-a-matrix-account) for free. + Alternatively, there are many [other providers](https://servers.joinmatrix.org/) you can choose that work in open federation. + +* If you're an [Ubuntu Member](https://ubuntu.com/community/membership) or work at Canonical, you can register an account {ref}`on the :ubuntu.com homeserver `. + + +(matrix-join-the-ubuntu-space)= +## Join the Ubuntu space + +Once you have an account and a client you can join the Ubuntu Space by typing `/join #community:ubuntu.com`, or by {matrix}`following this link `. +Here you'll get an overview of the most relevant chat rooms in our community. + + +## Follow the Code of Conduct + +When participating in the Ubuntu Community, including our Matrix channels, you agree to abide by the {ref}`Code of Conduct `. + +If you have an unpleasant experience where someone else is violating the Code of Conduct, report the message using your client. +In Element Web and Desktop, click on the three dots next to a message and select {guilabel}`Report`. +Community Moderators will receive your report and take appropriate action. + + +## Next steps + +Congratulations, by now you should be ready to chat with the Ubuntu community on Matrix. +Once you have introduced yourself, check out {ref}`matrix-completing-setup`. + diff --git a/docs/community/contributors/matrix/register-ubuntu-com.md b/docs/community/contributors/matrix/register-ubuntu-com.md new file mode 100644 index 00000000..98524279 --- /dev/null +++ b/docs/community/contributors/matrix/register-ubuntu-com.md @@ -0,0 +1,46 @@ +(matrix-register-ubuntu-com)= +# Register a Matrix account on `:ubuntu.com` + +Ubuntu Members and Canonical employees can register a Matrix account on the `:ubuntu.com` homeserver. +By registering on `:ubuntu.com`, you receive a Matrix ID with your Launchpad nickname and the `:ubuntu.com` suffix. + +To register, you need to use Element Desktop or Element Web. +For more info on how to get these, take a look at {ref}`how to install a Matrix client `. + +1. Start your client and select {guilabel}`Sign-in` (NOT {guilabel}`Create Account`) + +1. Click {guilabel}`Edit` next to `matrix.org` + +1. Select {guilabel}`Other homeserver` and type `ubuntu.com` + +1. Click on {guilabel}`Continue with SAML` and log in with your Ubuntu One account. + + ![Continue with SAML|703x550](continue-with-saml.png) + +1. After login, you'll see a page with your Matrix ID, e.g. `@username:ubuntu.com` -- press {guilabel}`continue` + +1. If you are using Element Desktop, you will be asked to open the link in the application -- open Element to confirm + +1. Ensure you create a secure backup of your keys, otherwise you will not be able to access your previous information and may not be able to log in + + +```{admonition} Username changes +:class: warning + +Your Matrix ID is directly tied to your _current_ Launchpad username. +If you ever change your Launchpad username, **you will lose access** to your old Matrix account and **somebody else could take it over** by creating a new Launchpad account with your old username. + +Therefore, if you ever change your Launchpad username: + +1. Immediately create a new Launchpad account with your old username, to ensure the old Matrix account cannot be taken over by anyone else! +1. Add your new Matrix account to all the private rooms your old account was part of +1. Give your new Matrix account the same permissions to all the rooms +1. Remove your old Matrix account from all the rooms +``` + + +## Next steps + +* To see our public rooms, {ref}`join the Ubuntu Space ` +* Configure the app so you can {ref}`use multiple Matrix accounts ` at the same time + diff --git a/docs/community/councils/communications-council.md b/docs/community/councils/communications-council.md index 39c60665..dd76175a 100644 --- a/docs/community/councils/communications-council.md +++ b/docs/community/councils/communications-council.md @@ -1,6 +1,16 @@ (communications-council)= # Communications Council +```{toctree} +:maxdepth: 1 +:hidden: + +matrix/matrix-council +matrix/matrix-operators +matrix/matrix-defenders +matrix/matrix-moderators +``` + The Ubuntu Communications Council (Comms Council) is responsible for looking after all aspects of communication for the Ubuntu Community. This includes both **synchronous communication platforms**, such as IRC, Matrix and Discord, and **asynchronous communication platforms**, such as Discourse, Ask Ubuntu, and the wiki. The Comms Council defines policies, moderation guidelines, and manages the platform-specific operator and moderator teams. They also work on a cohesive overarching strategy for Ubuntu's communications platforms, aiming to improve how our community collaborates, supports, and interacts. @@ -28,14 +38,14 @@ You can find the current council members in the [communications-council](https:/ Each platform has a team of operators that take care of the day-to-day activities of their respective platforms. They work with the Ubuntu Communications Council to implement changes and ensure their platforms are well maintained, governed, and that standard operating procedures are applied. -* [Matrix Operators](https://ubuntu.com/community/communications/matrix/governance#operators) +* {ref}`Matrix Operators ` * Discourse Moderators * [IRC Operators](https://wiki.ubuntu.com/IRC/IrcTeam) ## History -This council is a merger of old platform-specific councils like the IRC Council, Matrix Council, and Forums Council. This merger has multiple goals. +This council is a merger of old platform-specific councils like the IRC Council, {ref}`Matrix Council `, and Forums Council. This merger has multiple goals. **More cohesion and shared knowledge** : With the Matrix Council, we've seen how useful it is to have people from both the IRC and Matrix sides work together. It has really helped reduce the "rivalry" between platforms and the Matrix side learned a lot from the IRC side. It improved the speed of our decisions and we were better able to take the concerns from the IRC side into account. It also helped introduce senior people from the IRC side to the Matrix side. @@ -52,6 +62,7 @@ This council is a merger of old platform-specific councils like the IRC Council, **Enabling an overarching strategy** : With a Communications Council, the members can think about how all the platforms fit together into an overarching communication strategy. This will allow us to create a much better experience than what we have today with the informal coordination attempts between councils. + ## Election Council members are elected for a two-year term. To be eligible for the Ubuntu Communications Council, an individual must be an official Ubuntu Member. diff --git a/docs/community/councils/matrix/matrix-council.md b/docs/community/councils/matrix/matrix-council.md new file mode 100644 index 00000000..93941c63 --- /dev/null +++ b/docs/community/councils/matrix/matrix-council.md @@ -0,0 +1,46 @@ +(matrix-council)= +# Ubuntu Matrix Council + +The Matrix Council is highest governance body of the Ubuntu Matrix project. +They define the policies, the moderation guidelines, and appoint operators and defenders. + +Even though the Council has the end responsibility in these matters, **we encourage everyone to contribute**. +There is a lot of work ahead of us and they can't do it alone! +Public discussion with the Council and operators happens in the {matrix}`Ubuntu Matrix Ops ` room. + +You can find the authoritative list of current Council members in the [`matrix-council`](https://launchpad.net/~matrix-council/+members) team on Launchpad. + +The Council's term is limited until 2026-04-01. + + +(contact-matrix-council)= +## Contact the Ubuntu Matrix Council + +If you need to contact the Ubuntu Matrix Council, you can do so via the Ubuntu Discourse private message feature. + +* Login with your Ubuntu One account on the [Ubuntu Discourse](https://discourse.ubuntu.com). + +* Select the "hamburger menu" on the top navigation bar. + It is represented by three horizontal lines, and it is located between the search icon and your avatar. + +* From the drop-down menu, click on the {guilabel}`+` on the right of {guilabel}`Messages`. If you hover on it, a tool-tip will show {guilabel}`Create a personal message`. + +* Click on {guilabel}`Add users and groups`. + +* In the search field, type "matrix council". + +* Select "matrix-council *Ubuntu Matrix Council*". + +* Type a subject and a message. + +* Click on the {guilabel}`Message` icon when done. + + +## Further reading + +If you are keen to learn more about moderation and Matrix in general, take a look at these documents: + +* {ref}`using-matrix` +* {ref}`matrix-moderation-and-defense` +* {ref}`matrix-defenders` + diff --git a/docs/community/councils/matrix/matrix-defenders.md b/docs/community/councils/matrix/matrix-defenders.md new file mode 100644 index 00000000..bbdc9bf7 --- /dev/null +++ b/docs/community/councils/matrix/matrix-defenders.md @@ -0,0 +1,81 @@ +(matrix-defenders)= +# Matrix Defenders + + +Defenders help the Ubuntu community by fighting spam and other obvious forms of abuse within Matrix. +They are global moderators who help combat spam waves and obvious trolls across every official room of our homeserver. +This group has access to the Moderation bot in order to fulfill their duties. + +You can find the authoritative list of current Defenders in the [`matrix-defenders`](https://launchpad.net/~matrix-defenders) team on Launchpad. + +A Defender is not a Moderator, and will never get involved in moderation decisions beyond the cases described above. + + +## Expectations + +* Handling abusers of the service in a dispassionate and professional way +* Deferring all situations that aren't certain +* Being a high-trust individual for the level of privileges being granted + + +### Scope + +* Defenders may only act on newly interacting accounts on the Ubuntu Homeserver (by rough estimate of the Defender) +* If any situation is uncertain it should be passed to the room Moderators ({ref}`how-to-find-a-moderator`) +* Interpretation of events by a room owner or Moderator always take priority over a Defender + + +### Examples of abuse + +* Spamming +* Advertisement +* Extremely disruptive behavior + + +## How to contact a Defender + +Defenders can be contacted in the {matrix}`Matrix Ops ` room. +To draw Defenders' attention you can add `!defenders` in your message. + + +(how-to-become-a-defender)= +## How to become a Defender + +Defenders have very high privileges in the Matrix homeserver, and their actions have important consequences. +Because of that, they are hand-selected and appointed directly by the Matrix Council. + +Room owners can make recommendations to the Matrix Council, but only Ubuntu Members and Canonical employees are currently eligible. + +When our tooling improves so that Defenders need fewer permissions, we can open the role up to more people. + + +## Defender client configuration + +In order to receive urgent requests of help, Defenders need to set up a special filter in their Element client. +This will trigger room notifications in red, as if someone sent a private message. + +1. Open the Element client + +1. Hover over your user avatar, at the top left of the Element client + +1. Select {guilabel}`All Settings` + +1. Select the {guilabel}`Notifications` menu + +1. In the {guilabel}`Mentions & keywords` section, make sure that the {guilabel}`Messages containing keywords` is set to "On". + +1. In the text field marked with "Keyword" in the {guilabel}`Mentions & keywords` section, type `!defenders` + +1. Click on the {guilabel}`Add` icon to add the keyword + +1. Confirm you can see the keyword `!defenders` below the text field marked with "Keyword". + + +## Further reading + +If you want to become a Defender, or you are already one, refer to the documentation below for general direction and help: + +* {ref}`matrix-moderation-and-defense` +* {ref}`matrix-moderator-bot` +* {ref}`matrix-mjolnir-commands` + diff --git a/docs/community/councils/matrix/matrix-moderators.md b/docs/community/councils/matrix/matrix-moderators.md new file mode 100644 index 00000000..3a081331 --- /dev/null +++ b/docs/community/councils/matrix/matrix-moderators.md @@ -0,0 +1,61 @@ +(matrix-moderators)= +# Matrix Moderators + + +Moderators ensure everyone in an Ubuntu Matrix room follows the {ref}`Ubuntu Code of Conduct `. +They guide users towards positive behavior and collaborative communication, thereby fostering the Ubuntu community by ensuring Matrix rooms provide a safe and welcoming environment. + +Moderators are appointed by the room administrators. +Moderators protect specific Matrix rooms, because each room or space might have slightly different purpose and goals. +Having said that, they must all abide by the Ubuntu Code of Conduct. + + +## Expectations + +* Leading through example +* Fostering long-term successful room environments +* Detaching from situations when feeling pressured to act +* Willingness to seek guidance +* Intervening only when absolutely necessary + + +### Scope + +Moderators operate within the rooms they're entrusted to by the room owners. + + +### Example cases + +* Guiding people on how the room operates +* Helping facilitate room aspirations such as writing documentation, creating polls and performing leadership to achieve the owner's vision +* Fostering the [the spirit of Ubuntu](https://ubuntu.com/about) through example + + +(how-to-find-a-moderator)= +## How to find a Moderator + +Moderators can be found directly in the Matrix room you are using. +Since privileges aren't always visible over the IRC bridge, each room is required to list their Moderators in the room description. + +Failing that, Moderators will often have visible privilege levels by their name. +You can identify Moderators with the "Mod" tag in the "People" panel. + +For specific instructions, refer to {ref}`moderators-contact`. + + +(how-to-become-a-moderator)= +## How to become a Moderator + +Room owners and room administrators will select individuals, from among the activate participants of their room, who they think might make a good Moderator. + +Owners are encouraged to have an onboarding processes with a trial period before granting room privileges. + + +## Further reading + +If you want to become a Moderator, or you are already one, refer to the documentation below for general direction and help: + +* {ref}`matrix-moderation-and-defense` +* {ref}`matrix-moderator-bot` +* {ref}`matrix-mjolnir-commands` + diff --git a/docs/community/councils/matrix/matrix-operators.md b/docs/community/councils/matrix/matrix-operators.md new file mode 100644 index 00000000..e2be44e4 --- /dev/null +++ b/docs/community/councils/matrix/matrix-operators.md @@ -0,0 +1,13 @@ +(matrix-operators)= +# Matrix Operators + +Operators help the {ref}`matrix-council` with making sure the Ubuntu Matrix platform is running smoothly. +They help define policies, write documentation, and do day-to-day management tasks such as publishing rooms. +Operators typically join Matrix Council meetings, although they have no formal voting power. + +You can find the authoritative list of current Operators in the [`matrix-operators`](https://launchpad.net/~matrix-operators/+members) team on Launchpad. + +Operators are appointed by the Matrix Council. + +Former Matrix Council members have Operator status. + diff --git a/docs/community/how-ubuntu-is-made/matrix/both-spaces-joined.png b/docs/community/how-ubuntu-is-made/matrix/both-spaces-joined.png new file mode 100644 index 00000000..72fa3190 Binary files /dev/null and b/docs/community/how-ubuntu-is-made/matrix/both-spaces-joined.png differ diff --git a/docs/community/how-ubuntu-is-made/matrix/bridging-integrations.md b/docs/community/how-ubuntu-is-made/matrix/bridging-integrations.md new file mode 100644 index 00000000..b49bf184 --- /dev/null +++ b/docs/community/how-ubuntu-is-made/matrix/bridging-integrations.md @@ -0,0 +1,97 @@ +(matrix-bridging-integrations)= +# Bridging and integrations + + +## Bridging + + +### Bridging with IRC + +Bridging with Ubuntu IRC is being investigated with the IRC Council. +This is the only bridging priority at the moment. +IRC is the official Ubuntu synchronous communications tool and having a stable, self hosted bridging solution is really important. +It is also important to get it right. +Please stay tuned here for further information. + + +### Bridging with other chat platforms + +Self hosting bridges with chat platforms outside of IRC is currently not on our roadmap. + + +## Integrations + + +### Integrations showroom + +If you want to see what Matrix is capable as a platform, you can look at our showroom space and rooms. +You can join {matrix}`this public space ` and the rooms in it. +Various integrations are displayed as examples. +All integrations used are hosted by Element. + + +### Element-hosted integrations + +A series of integrations hosted by Element are available on the Ubuntu Matrix instance. +Room admins need to decide if they want to grant use of those or not. +Please note those are not provided by Ubuntu, and the Ubuntu project cannot guarantee uptime for those integrations. + + +### Ubuntu self-hosted integrations + +We are currently considering various self hosted integrations, but we are unable to provide further information or timeline yet. + + +(matrix-irc-bridging-limitations)= +## Matrix-to-IRC bridging limitations + +This document outlines what to expect when Ubuntu starts bridging existing IRC channels to Matrix rooms. + + +### Bridging events from IRC to Matrix + +There are no limitations bridging messages from IRC to Matrix. +All features are supported and translated to Matrix events. + + +### Unavailable or limited Matrix to IRC events + +**Redaction** +: Redacting messages on Matrix has no effect on the IRC side. The message just stays as written. + +**HTML/Markdown** +: Some Markdown language is supported. For example you can use **bold text**. If a Markdown feature is not supported (like code blocks) the message is usually transmitted as plain text. + +**Media sharing** +: Matrix supports sharing images, videos, and files directly in chats. IRC does not inherently support media sharing. Files must be shared via URLs. Any direct media shared on Matrix will typically be converted to a URL when viewed on IRC. + +**Reply threads** +: Matrix supports threaded conversations, allowing users to reply to specific messages creating a thread. IRC does not support threads in the same way, so threaded messages from Matrix will appear as standard messages on IRC, potentially losing context. + +**Reactions and emojis** +: While both Matrix and IRC support the use of emojis in messages, Matrix also supports message reactions (emoji reactions to messages). These reactions do not have a direct equivalent in IRC and will not be visible. + +**Read receipts and typing notifications** +: Matrix provides read receipts and typing notifications to indicate when users are typing a message or have read a message. IRC does not support these features, so they are not available when bridging from Matrix to IRC. + +**End-to-end encryption** +: Matrix supports end-to-end encryption in rooms. IRC does not support end-to-end encryption natively; thus, encrypted messages cannot be bridged to IRC without losing encryption. + +**Room features** +: Features like room topics are supported by both protocols but may not always sync perfectly across the bridge. Changes made on the Matrix side may not be reflected on IRC or may be subject to limitations based on the IRC network's capabilities. Room avatars on Matrix are not visible on IRC. + +**Nicknames and user IDs** +: Matrix allows for more flexibility in usernames and displays, including spaces and special characters. IRC has stricter rules for nicknames (limited character set and length), which might result in automatic adjustments or truncation when bridging. + +**Kick/ban synchronization** +: While basic kick and ban actions can be synchronized between Matrix and IRC, the granularity of reasons, temporary bans, and more complex moderation actions may not translate perfectly across the bridge. In general, moderation must be done on both sides. + +**Channel modes and permissions** +: IRC has a specific set of channel modes and user permissions that do not have a direct equivalent in Matrix. Bridging these settings can be challenging and may result in a loss of functionality or mismatched permissions. The map below shows the conversion of IRC user modes to Matrix power levels. This enables bridging of IRC Ops to Matrix power levels only -- it does not enable the reverse. If a user has been given multiple modes, the one that maps to the highest power level will be used. + +| IRC mode | Matrix permission level | +| -------- | ----------------------- | +| None | 0 | +| Voice | 1 | +| Operator | 50 (Moderator) | + diff --git a/docs/community/how-ubuntu-is-made/matrix/index.md b/docs/community/how-ubuntu-is-made/matrix/index.md new file mode 100644 index 00000000..9624c0b9 --- /dev/null +++ b/docs/community/how-ubuntu-is-made/matrix/index.md @@ -0,0 +1,23 @@ +(matrix-index)= +# Matrix + + +Matrix is an instant messaging (IM) platform where you can talk to Ubuntu community members, on topics ranging from idle chit-chat, over community improvements, to support with your Ubuntu. + +In this section you will be able to find core concepts on how Matrix works. +You will learn about the protocol, rooms, spaces, and federation. +You will also read about how Matrix is different from most other synchronous communication platforms. + +If you just want to get set up and start chatting, take a look at our {ref}`onboarding instructions `. + + +```{toctree} +:maxdepth: 1 + +rooms-spaces-concepts +matrix-room-publishing +moderation-and-defense +moderator-bot +bridging-integrations +``` + diff --git a/docs/community/how-ubuntu-is-made/matrix/matrix-room-publishing.md b/docs/community/how-ubuntu-is-made/matrix/matrix-room-publishing.md new file mode 100644 index 00000000..91f2e415 --- /dev/null +++ b/docs/community/how-ubuntu-is-made/matrix/matrix-room-publishing.md @@ -0,0 +1,15 @@ +(matrix-room-publishing)= +# Room publishing + +In Matrix, each server has the concept of a room directory. +It acts as the server's "front page", highlighting essential rooms for newcomers and showcasing the most active and general community discussions. +Consider publishing if your room serves as a gateway for new members into the Ubuntu community or discusses key Ubuntu topics. +The room directory is the entry point for people exploring Ubuntu through the search feature in their Matrix client. + +Users joining rooms through the room directory will have no immediate way to explore unpublished rooms, and it remains a flat list. +Therefore, we're also making use of the spaces feature to group rooms and put them in a hierarchy. +This allows potential contributors to explore the Ubuntu ecosystem and join the niche they are most interested in. +We will be linking the Ubuntu Community space in our documentation as an entry point. + +Learn {ref}`how to publish your room ` and add it to the Ubuntu Community space. + diff --git a/docs/community/how-ubuntu-is-made/matrix/moderation-and-defense.md b/docs/community/how-ubuntu-is-made/matrix/moderation-and-defense.md new file mode 100644 index 00000000..82bbb06c --- /dev/null +++ b/docs/community/how-ubuntu-is-made/matrix/moderation-and-defense.md @@ -0,0 +1,72 @@ +(matrix-moderation-and-defense)= +# Moderation and defense of our Matrix community + +## Our Mission + +The Ubuntu Matrix homeserver is meant to reflect the values of the Ubuntu Community. +It should be an open, transparent and welcoming environment to everyone from across the globe. + +We believe a welcoming and diverse community should look like a patchwork quilt of different ideas and beliefs across all kinds of people working toward a common purpose. +The spirit of this mission is codified in the **{ref}`Ubuntu Code of Conduct `** and our **{ref}`Diversity policy `**, which applies to all official rooms on the Ubuntu Matrix homeserver and clarifies the underlying intention of all roles. + +We have two types of people who help us achieve this goal: + +* **Defenders**, who operate across all public rooms and fight clear cases of spam and abuse by newly interacting accounts +* **Moderators**, who take care of individual rooms, helping foster welcoming and collaborative environments while managing conflict resolution and handling poor conduct + +The remainder of this document explains these roles in more detail. + +## "Defenders" fight abuse + +Defenders fight clear abuse and spam. +They operate across **all** public Ubuntu Matrix rooms. + +Speed and coverage are important to this role as it deals with the vast majority of issues which are blatant abuses of the service by newly interacting accounts. + +{ref}`Read more about Matrix Defenders > ` + + +## Room administrators + +Room administrators manage a room on the Ubuntu Matrix homeserver and are responsible for day-to-day moderation. +They ensure the room conforms to our guidelines, and appoint moderators for their room. + +Anyone can become a room administrator by creating a room. + + +## "Moderators" foster the community + +Moderators are appointed by room owners to help achieve the aspirations of their room while keeping it a distinctly {ref}`Ubuntu place `. + +Some rooms may have mechanical expectations such as strict Q&A where others may be open to varying types and degrees of banter. + +Thoughtfulness, flexibility and humility are important to this role. + +{ref}`Read more about Matrix Moderators > ` + + +### Are room owners also moderators? + +Not necessarily. Although room owners are ultimately responsible for ensuring their room is well-moderated, they're not required to do the moderation themselves. +They can appoint other people to become moderators. + + +### Are room moderators also defenders? + +Moderators are a fallback if no defenders are available. +However, moderators should only perform this duty when it doesn't interfere or impede on the time required to perform their best moderator work. + + +## Policies + +### Room descriptions + +Room descriptions should contain a link to the {ref}`Ubuntu Code of Conduct ` and a list of room moderators to contact in case of an issue. + + +### Non-interaction policy + +Newly interacting accounts that are abusing the service through methods like spam, advertisement and nefarious motives are strictly to be ignored. + +Engagement is valuable to these accounts and interacting with them adds unnecessary load to the maintenance of the Ubuntu homeserver and its defenders. + diff --git a/docs/community/how-ubuntu-is-made/matrix/moderator-bot.md b/docs/community/how-ubuntu-is-made/matrix/moderator-bot.md new file mode 100644 index 00000000..2520b908 --- /dev/null +++ b/docs/community/how-ubuntu-is-made/matrix/moderator-bot.md @@ -0,0 +1,42 @@ +(matrix-moderator-bot)= +# Moderator bot + +This document explains what the moderator bot is, what it does, and why we need it. + + +## Who is the moderator I see in my room? + +You may have noticed an account called "moderator", with the alias: `@moderator:ubuntu.com` in your room or space. +This is not a personal account, but a moderator bot we use to protect our Ubuntu Matrix homeserver from spam and abuse. +This is part of our process for {ref}`publicly listed rooms and spaces `. + + +## What does the moderator bot do? + +The moderator bot we currently used has several features: + +* Being a room admin, it keeps a foothold in each of our rooms and spaces. + No matter what happens to other admin users in the room or space, the moderator will always allow the Matrix Ops to regain control when needed. + +* Moderator bot is subscribed to federated access lists (ACLs) from other servers we trust. + So, if a person or spam-bot is banned from communities we follow, the same account is automatically banned from our Ubuntu Matrix homeserver. + This blocks spam before it can even start. + +* Other Matrix homeservers can listen to our access list and gain the same advantages, so that accounts we ban are automatically banned on friendly homeservers as well. + +* Room users can ask for help in the Matrix Ops room in case of a spam wave, and server-level bans can be performed by Matrix Ops team through the moderator bot. + + +## Why do we need to grant admin permissions to the moderator bot? + +* It ensures that a malicious user trying to take over a room cannot kick out the bot. + +* It ensures the Matrix Operators can always regain control of a room, even if all admins leave, lose their accounts, or are locked out of the platform. + Due to how Matrix federation works, it might otherwise be impossible to regain control of a room, even as a server admin. + +* It allows the bot to configure sensitive settings such as default power levels. + + +## Who will ask me for this permission? + +All official communication about these permissions will come from either the {ref}`Matrix Council ` or one of the {ref}`Operators `. diff --git a/docs/community/how-ubuntu-is-made/matrix/one-space-joined.png b/docs/community/how-ubuntu-is-made/matrix/one-space-joined.png new file mode 100644 index 00000000..530cd1b6 Binary files /dev/null and b/docs/community/how-ubuntu-is-made/matrix/one-space-joined.png differ diff --git a/docs/community/how-ubuntu-is-made/matrix/rooms-spaces-concepts.md b/docs/community/how-ubuntu-is-made/matrix/rooms-spaces-concepts.md new file mode 100644 index 00000000..9dc54081 --- /dev/null +++ b/docs/community/how-ubuntu-is-made/matrix/rooms-spaces-concepts.md @@ -0,0 +1,60 @@ +(matrix-rooms-spaces-concepts)= +# Rooms and spaces + +## Matrix rooms + +Chat rooms on Matrix are not exactly the same as on other platforms. +A room is created on a specific Matrix instance, but can be very easily replicated over to many other servers. + + +## Matrix room properties + +**Internal ID** +: A Matrix room has a few basic properties that cannot be changed, such as its Internal ID (e.g., `!FHUUPIuRjbTaUxVYGa:ubuntu.com`). This internal identifier has a suffix, but that doesn't mean that the room is only on `:ubuntu.com`. Instead, the room is replicated on every server that has someone participating in it. For example, if someone with a matrix.org account joins, the same room exists on both servers at the same time and is kept in sync. + + +**Aliases** +: Aliases are what map a readable identifier to the room Internal ID. Each server can have their own alias for a room, so the same room can have both the alias `#room:ubuntu.com`, and `#ubuntu-room:matrix.org`. People joining through each of these IDs will not notice the difference. + +: A room can have its main alias changed, or aliases added, completely transparently. Users won't need to be migrated, even if it means "moving" a room into another homeserver. + +: A room is an independent item in the Matrix federated environment. Therefore, each room alias and name should be descriptive and give enough context to people that browse it or search for it. This is also true if the room is part of a space. + + +Public rooms should be unencrypted. There is no advantage in encrypted public room. It is not possible to search the room history or configure mentions and keywords in encrypted rooms. To {ref}`publish your public room ` encryption must be turned off. + + +## Matrix spaces + +Matrix spaces are collections of rooms and/or other spaces. +However, they work in a unique way on Matrix. +A Matrix space can simply be considered a tag, a label, or a symbolic link, not a folder or sub-folder. + +* Spaces can be listed under other spaces (i.e. Charmhub is listed under Ubuntu Community) +* A space or a room can be listed on multiple spaces +* A user can join a space or a room without joining any of the spaces it is listed in + +{ref}`Learn more about room properties > `. + + +### Spaces on the Element client + +As we established earlier, spaces are not hierarchical on Matrix, but act like symbolic links on Linux. +Or like tags or labels on an email client. +Spaces can be listed under other spaces, and the way they are displayed on the Element client depends on how many of those nested spaces a user joined. +On the left, we can see an example of a user who joined both the *Release Testing* and the *Ubuntu Testing* spaces. +In the Element client, they appear nested. +This is a design choice of the Element client, not representative of a universal hierarchy. +On the right, the same user joined the *Ubuntu Release Testing* space but not the *Ubuntu Testing* space. +As we can see, the Ubuntu Release Testing space is now shown as a top level space in the Element client. + +::::{grid} 2 +:::{grid-item-card} Both spaces are joined +![|136x337](both-spaces-joined.png) +::: +:::{grid-item-card} Only one space is joined +![|138x342](one-space-joined.png) +::: +:::: + + diff --git a/docs/community/index.md b/docs/community/index.md index 2b731bfb..d1006905 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -7,5 +7,6 @@ ethos/index governance/index +how-ubuntu-is-made/matrix/index contribute/contribute ``` diff --git a/docs/community/matrix/index.md b/docs/community/matrix/index.md new file mode 100644 index 00000000..2999b289 --- /dev/null +++ b/docs/community/matrix/index.md @@ -0,0 +1,34 @@ +(matrix-management)= +# Matrix management + +This section is aimed at Matrix room administrators, owners and moderators. +In it, you will learn how to create, publish and maintain rooms. + +If you are the owner of a room, feel free to help flesh out this documentation. + + +## Create a room or space + +```{toctree} +:maxdepth: 1 + +room-creation/index +``` + + +## Room ownership + +```{toctree} +:maxdepth: 1 + +room-ownership/index +``` + + +## Room moderation + +```{toctree} +:maxdepth: 1 + +moderation/matrix-moderation +``` diff --git a/docs/community/matrix/moderation/matrix-moderation.md b/docs/community/matrix/moderation/matrix-moderation.md new file mode 100644 index 00000000..6747d7e8 --- /dev/null +++ b/docs/community/matrix/moderation/matrix-moderation.md @@ -0,0 +1,19 @@ +(matrix-moderation)= +# Matrix moderation + +To foster a thriving and outspoken community, good moderation processes and practices are a necessity. + +In this section, you will read all about our moderation vision and style. +You will learn how to protect your rooms, spotlight outstanding moderators, and request help from the community. + + +## Moderation processes + +```{toctree} +:maxdepth: 1 + +Making rooms official +room-moderation +mjolnir-commands +``` + diff --git a/docs/community/matrix/moderation/mjolnir-commands.md b/docs/community/matrix/moderation/mjolnir-commands.md new file mode 100644 index 00000000..aa1becc2 --- /dev/null +++ b/docs/community/matrix/moderation/mjolnir-commands.md @@ -0,0 +1,201 @@ +(matrix-mjolnir-commands)= +# Mjolnir commands + + +Mjolnir listens for commands in {matrix}`the management room `. +This room is private and only server moderators are granted access to it. + + +## Print a list of commands + +A comprehensive list of Mjolnir commands can be printed using the command below in {matrix}`the management room `. + +```none +!mjolnir help +``` + + +## To enable Mjolnir protection in rooms + +This process is well described in {ref}`matrix-rooms-spaces-process`. + + + +## Moderation commands + +### Redacting user messages + +Redacting messages does not kick or ban a particular user, so they could continue their activity. +In certain cases of spam waves, it might be beneficial to kick and ban as well as redacting. + + +Redact last 100 messages in a specific room +: Command syntax: + ```none + !mjolnir redact [room alias/ID] [limit] + ``` + +: Example: + ``` + !mjolnir redact @user:ubuntu.com #room:ubuntu.com 100 + ``` + +Redact last 100 messages globally +: Command syntax: + ```none + !mjolnir redact [limit] + ``` + +: Example: + ```none + !mjolnir redact @user:ubuntu.com 100 + ``` + + +### Mute a user + +Mute or silence a user by setting their "power level" negative: + +```none +!mjolnir powerlevel @user:matrix.org -1 #room:ubuntu.com +``` + + +### Kick a user + +Kicking removes a user from a room temporarily. +This is not a permanent ban from the room. + + +Kick using moderation reports +: With moderation reports, you can click on the "kick" button below a report. Mjolnir will take action and kick the user according to the details in the report. + + +Manually kick user from specific room +: Command syntax: + ```none + !mjolnir kick [room alias/ID] [reason] + ``` + +: Example: + ```none + !mjolnir kick @user:ubuntu.com #room:ubuntu.com [spam] + ``` + + +Manually kick a user from all protected rooms +: Command syntax: + ```none + !mjolnir kick [reason] + ``` + +: Example: + ```none + !mjolnir kick @user:ubuntu.com spam + ``` + + +### Ban users + +A ban removes a user from a homeserver inefinitely. +This is not a permanent ban from the room. +This action is useful in case of repeat offenders or obvious bot spam action. + + +Ban using moderation reports +: With moderation reports, you can click on the "ban" button below a report. Mjolnir will take action and ban the user according to the details in the report. + + +Manually ban user for Code of Conduct violations +: Command syntax: + ```none + !mjolnir ban [reason] + ``` + +: Example: + ```none + !mjolnir ban coc user @user:ubuntu.com inappropriate and aggressive behavior + ``` + + +Manually ban user for spam +: Command syntax: + ```none + !mjolnir ban [reason] + ``` + +: Example: + ```none + !mjolnir ban spam user @user:ubuntu.com spamming inappropriate messages + ``` + + +### Ban servers + +A server ban prevents users from an entire server to join the ubuntu.com homeserver. +This is particularly useful to block spam waves, when hundreds of users are created on the same homeserver. + +Command syntax: + +```none +!mjolnir ban [reason] +``` + +As you probably guessed, you are not going to ban a user this time, but a server. For example, to ban the `maliciousdomain.tld` domain: + +```none +!mjolnir ban spam server maliciousdomain.tld +``` + + +## Full list of commands + +```none +!mjolnir - Print status information +!mjolnir status - Print status information +!mjolnir status protection [subcommand] - Print status information for a protection +!mjolnir ban [reason] - Adds an entity to the ban list +!mjolnir unban [apply] - Removes an entity from the ban list 0 - if apply is 'true', the users matching the glob will actually be unbanned +!mjolnir redact [room alias/ID] [limit] - Redacts messages by the sender in the target room (or all rooms), up to a maximum number of events in the backlog (default 1000) +!mjolnir redact - Redacts a message by permalink +!mjolnir kick [room alias/ID] [reason] - Kicks a user or all of those matching a glob in a particular room or all protected rooms +!mjolnir rules - Lists the rules currently in use by Mjolnir +!mjolnir rules matching - Lists the rules in use that will match this entity e.g. `!rules matching @foo:example.com` will show all the user and server rules, including globs, that match this user +!mjolnir sync - Force updates of all lists and re-apply rules +!mjolnir verify - Ensures Mjolnir can moderate all your rooms +!mjolnir list create - Creates a new ban list with the given shortcode and alias +!mjolnir watch - Watches a ban list +!mjolnir unwatch - Unwatches a ban list +!mjolnir import - Imports bans and ACLs into the given list +!mjolnir default - Sets the default list for commands +!mjolnir deactivate - Deactivates a user ID +!mjolnir protections - List all available protections +!mjolnir enable - Enables a particular protection +!mjolnir disable - Disables a particular protection +!mjolnir config set . [value] - Change a protection setting +!mjolnir config add . [value] - Add a value to a list protection setting +!mjolnir config remove . [value] - Remove a value from a list protection setting +!mjolnir config get [protection] - List protection settings +!mjolnir rooms - Lists all the protected rooms +!mjolnir rooms add - Adds a protected room (may cause high server load) +!mjolnir rooms remove - Removes a protected room +!mjolnir rooms setup reporting - Setup decentralized reporting in a room +!mjolnir move - Moves a to a new +!mjolnir directory add - Publishes a room in the server's room directory +!mjolnir directory remove - Removes a room from the server's room directory +!mjolnir alias add - Adds to +!mjolnir alias remove - Deletes the room alias from whatever room it is attached to +!mjolnir resolve - Resolves a room alias to a room ID +!mjolnir since / [rooms...] [reason] - Apply an action ('kick', 'ban', 'mute', 'unmute' or 'show') to all users who joined a room since / (up to users) +!mjolnir shutdown room [message] - Uses the bot's account to shut down a room, preventing access to the room on this server +!mjolnir powerlevel [room alias/ID] - Sets the power level of the user in the specified room (or all protected rooms) +!mjolnir make admin [user alias/ID] - Make the specified user or the bot itself admin of the room +!mjolnir help - This menu +``` + + +## Further reading + +* [Matrix documentation: moderating communities](https://matrix.org/docs/communities/moderation/) +* [Moderator's guide to Mjolnir (Bot edition)](https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md) + diff --git a/docs/community/matrix/moderation/room-moderation.md b/docs/community/matrix/moderation/room-moderation.md new file mode 100644 index 00000000..496de0dc --- /dev/null +++ b/docs/community/matrix/moderation/room-moderation.md @@ -0,0 +1,65 @@ +(matrix-room-moderation)= +# Room moderation and policies + + +This document outlines roles and responsibilities of room owners and room moderators. +If you are looking to create a new room in the Ubuntu Matrix homeserver, make sure you follow the {ref}`official process `. + + +## Room owners + +Room owners are responsible for all conduct within their room. +In order to share load and responsibilities, it would be ideal to also have a few moderators (mods) in each room. +The general preference of the Ubuntu Matrix Council is that there should not be a formal process to become a moderator. +Instead, room owners can offer the moderator role to members of their community. +This ensures alignment with the moderation style and vision of the Ubuntu homeserver. +In order for this to work at scale, room owners are encouraged to read {ref}`matrix-moderation-and-defense`. + + +## Room moderators + +Once room owners identify a potential candidate to be a room moderator, they have the authority to grant them moderator (mod) power level. +Before doing so, it is also recommended that potential new room moderators read the {ref}`Ubuntu Code of Conduct ` and {ref}`matrix-moderation-and-defense`. +Room moderators should also join the {matrix}`Ubuntu Matrix Ops room ` where they can ask for help or start discussions as needed. + + +## Defender spotlight + +Room owners are empowered to identify and spotlight outstanding moderators to become Defenders. +This applies only to users that have an account on the Ubuntu Matrix homeserver. +Room owners can reach out to room moderators that are in line with the moderation style and vision of the Ubuntu Matrix homeserver, ask them if they would be willing to be spotlighted to become a Defender. +If the room moderator agrees, the Room owner can reach out to {matrix}`the Matrix Ops team ` and link the Matrix handle of the moderator they would like to spotlight. +The Ops team will start a process to mentor and train the upcoming server moderator, and once a positive outcome has been reached, the candidate is granted server moderator status. + + +## Abandoned room policy + +Once a room is abandoned by all mods and admins, the Matrix Operators will take over. +They may appoint new admins and mods, or close the room. + +* Leaving a room as an admin is not alone enough to abandon a room -- we don't want people who briefly leave after getting upset to suddenly lose their room. + A certain time period will of being absent from a room without prior planning would be considered abandonment (what that time period is has not yet been determined). + +* The Council will not get involved if a user who is an admin or mod abandons a room but other admins and mods are still in the room. + The abandoning user will retain their power as admin or mod if they come back. + Room admins and mods can come to the Council to ask for the Council's intervention if they so desire. + +* If all admins abandon a room but mods are left, the Council may need to appoint new admins while leaving the existing mods in place (or promoting one or more of them to admin). + This should be handled on a case-by-case basis since some rooms may have different concerns in this area than others. + As a general rule, unless there was a misconduct report for the admin(s) who left, we will not strip admin permissions from them. + We did not yet decide on a process for if new admins do need to be elected. + + +## Governance + +All rooms on our homeserver fall under the {ref}`Ubuntu Matrix Governance ` policy. +The {ref}`matrix-council` has the final say in the policies of our homeserver. + + +## Further reading + +Understand the basic concepts of: +* {ref}`Rooms and spaces ` +* {ref}`Room properties ` +* {ref}`Room publishing ` + diff --git a/docs/community/matrix/moderation/rooms-spaces-process.md b/docs/community/matrix/moderation/rooms-spaces-process.md new file mode 100644 index 00000000..2f148a58 --- /dev/null +++ b/docs/community/matrix/moderation/rooms-spaces-process.md @@ -0,0 +1,76 @@ +(matrix-rooms-spaces-process)= +# Official rooms and spaces process + +Users on the Ubuntu Matrix homeserver should be free to create rooms and spaces as they see fit. +This encourages interaction and keeps operations fast and smooth. +Having said that, we also want to make sure that all the official rooms and their owners follow our guidelines and are aware of rules, expectations, and processes. +For a user to promote a room or space to official, they need to contact the Matrix Ops team and ask to have it published in the server directory and listed under the Ubuntu Community space. + +Users on the Ubuntu Matrix homeserver do not have permissions to publish their spaces or rooms in the server room directory. +They also do not have permissions to list their spaces or rooms under the main Ubuntu Community space. + +This document describes a complete list of tasks that need to happen when new room or space owner reaches out to Matrix Ops asking to make their room or space official. + + +## Space/room owner contacts moderators + +Users create spaces or rooms, then they contact the moderators in {matrix}`matrix-ops` as described in {ref}`matrix-rooms-spaces`. + + +## Awareness + +Moderators in the {matrix}`matrix-ops` room, share documentation that every space/room owner should read. +The documents describe their responsibilities and requirements for an official Ubuntu room. + + +## Invite moderator bot + +Room owners will invite the moderator bot, `@moderator:ubuntu.com` to their rooms, and assign admin privileges to the bot. +This is required so that the moderator bot can perform automated actions or other operations when invoked by moderators. +The room owner will inform the moderators when the actions are completed. + +Moderators will then enable protection on the rooms, by sending these moderator bot commands in {matrix}`the management room `: + +* Check moderator bot status: `!mjolnir status` + +* Check rooms protected by the moderator bot: `!mjolnir rooms` + +* Add the room to the protected rooms list: `!mjolnir rooms add ` + +* Check moderator bot status one more time to make sure everything looks good: `!mjolnir status` + + +## Ubuntu Code of Conduct banner + +The moderator will ensure the room owner added a link to the Ubuntu Code of Conduct to the room description: + +```none +Please follow the CoC: https://ubuntu.com/community/ethos/code-of-conduct +``` + + +## Room mod and room admin + +The moderator will make sure that the room owner is aware of the following: + +* Each room should have two admins. + This helps with redundancy, as there are some actions only admins can take. + +* Admin status cannot be removed by another admin, as they are on the same power level. + Do not grant admin status lightly. Mod is enough for most needs. + +* The room owner should identify suitable mods that can help protect the room from spam, abuse, and other unwanted behavior. + +* Room owners are encouraged to keep an eye on great mods and refer them to the Matrix Council as server moderators. + + +## List and publish spaces/rooms + +The moderator will list the spaces and/or rooms in the server directory by enabling the flag in the room configuration -> general settings. + +```none +Publish this room to the public in ubuntu.com's room directory? +``` + +The moderator will list the space/room in the main {matrix}`Ubuntu Community space `. + diff --git a/docs/community/matrix/room-creation/create-a-private-room.md b/docs/community/matrix/room-creation/create-a-private-room.md new file mode 100644 index 00000000..e82bfbd8 --- /dev/null +++ b/docs/community/matrix/room-creation/create-a-private-room.md @@ -0,0 +1,81 @@ +(matrix-room-creation-private)= +# Create and configure a private room + +This short guide walks you through the creation and basic configuration of a public room on the Ubuntu Matrix homeserver. +This guide assumes you are using the Element desktop client. + +```{note} +Anyone with an `ubuntu.com` account can create private rooms on our homeserver. +``` + + +## Create a private room + +1. Click on the {guilabel}`All rooms` icon on the top left of your Element desktop client. + This icon is represented by a house, and can be found below the user avatar. + +1. Click on the {guilabel}`+` icon on the left of {guilabel}`Home` and below the compass icon used to search for rooms. + Select {guilabel}`New Room`. + + ```{warning} + It is important to ensure you are **on your home screen** when clicking on the {guilabel}`+` icon. + Otherwise, it will try to create a room _inside_ the space you're currently in. + This will fail in the Ubuntu space. + If you want to add a room to one of our spaces, first create the room outside of the space, and then follow {ref}`matrix-rooms-spaces`. + +1. In the {guilabel}`Name` field, type the display name of the room. + This name can contain upper and lower case characters, spaces, and can be changed later. + +1. The {guilabel}`Topic` field is for the description of your room. + This field is optional and can be filled later. + +1. In the dropdown, select {guilabel}`Private room (invite only)`. + +1. The last but most important choice to make is about end-to-end encryption. + + ```{warning} + The recommendation is to toggle encryption off *before* creating the room. + Disabling encryption later on is not possible. + Enabling encryption will cause issues with bots, bridges, and overall lower the quality of user experience of your room. + ``` + +1. Double-check your settings, then click on {guilabel}`Create room`. + + +## Room configuration + +### General settings + +1. After your room is created, click on the room name dropdown on the top of your Element desktop client, and select {guilabel}`Settings`. + +1. In the {guilabel}`General` settings, you can change "Room Name", "Room Topic", and add a "Room image". + +1. In the {guilabel}`General` settings, you can also check your published addresses, and local addresses. + If you cannot enable the {guilabel}`Publish this room to the public in the ubuntu.com's room directory?` toggle, please note this is intended behavior. + Check steps in the {ref}`private-room-publishing` section to complete this task. + + +## Security and privacy settings + +In the {guilabel}`Security & Privacy` settings, you can change your room from Private to Public, or space members. + +```{warning} +Please **never enable encryption** for public rooms. +You cannot turn it back off, and it creates a lot of issues with public rooms. +``` + + +(private-room-publishing)= +## Room publishing and listing under spaces + +Please check {ref}`matrix-rooms-spaces` if you'd like to: + +* Protect your room from abuse +* Publish your room in the server directory +* Add your room to the Ubuntu Community space + + +## Further reading + +Congratulations! Your private room is now ready! +If you would like to learn more about the Ubuntu Matrix homeserver, check {ref}`our documentation `. diff --git a/docs/community/matrix/room-creation/create-a-private-space.md b/docs/community/matrix/room-creation/create-a-private-space.md new file mode 100644 index 00000000..dd062bfd --- /dev/null +++ b/docs/community/matrix/room-creation/create-a-private-space.md @@ -0,0 +1,53 @@ +(matrix-space-creation-private)= +# Create and configure a private space + + +This short guide walks you through the creation and basic configuration of a private space on the Ubuntu Matrix homeserver. +This guide assumes you are using the Element desktop client. + +```{note} +A Matrix Space is technically a type of room. +Reference to rooms in this guide are intentional, to stay aligned with the Element client interface. +``` + + +## Create a private space + +1. Click on the {guilabel}`+` icon on the left panel, below your user avatar. + +1. Select {guilabel}`Private`. + +1. In the {guilabel}`Name` field, type the display name of the space. + This name can contain upper and lower case characters, spaces, and can be changed later. + +1. In the {guilabel}`Description` field, you can add a description of this space. + This field is optional and can be filled later. + +1. Select {guilabel}`Create`. + + +## Space configuration + +### General settings + +1. After your space is created, click on the space name drop-down on the left side of your Element desktop client, under the search bar, and select {guilabel}`Settings`. + +1. In the {guilabel}`General` settings, you can change "Name", "Description", and upload an image. + +1. Once all changes are confirmed, select {guilabel}`Save Changes`. + + +### Visibility + +In the {guilabel}`Visibility` settings, you can: + +* Change your space from Public to Private, or space members. + +* Enable or disable space preview. + Keeping this option disabled is recommended for public spaces. + + +## Further reading + +Congratulations! Your private space is now ready! +If you would like to learn more about the Ubuntu Matrix homeserver, check {ref}`our documentation `. diff --git a/docs/community/matrix/room-creation/create-a-public-room.md b/docs/community/matrix/room-creation/create-a-public-room.md new file mode 100644 index 00000000..a89b0095 --- /dev/null +++ b/docs/community/matrix/room-creation/create-a-public-room.md @@ -0,0 +1,79 @@ +(matrix-room-creation-public)= +# Create and configure a public room + + +This short guide walks you through the creation and basic configuration of a public room on the Ubuntu Matrix homeserver. +This guide assumes you are using the Element desktop client. + +```{note} +Anyone with an `ubuntu.com` account can create public rooms on our homeserver. +However, to publish the room on the homeserver or in our spaces, you need to follow the rules explained in {ref}`matrix-rooms-spaces`. +``` + + +## Create a public room + +1. Click on the {guilabel}`All rooms` icon on the top left of your Element desktop client. + This icon is represented by a house, and can be found below the user avatar. + +1. Click on the {guilabel}`+` icon on the left of {guilabel}`Home and below the compass icon used to search for rooms. + Select "New Room". + ```{warning} + It is important to ensure you are **on your home screen** when clicking on the {guilabel}`+` icon. + Otherwise, it will try to create a room *inside* of the space you're currently in. + This will fail in the Ubuntu space. + If you want to add a room to one of our spaces, then first create the room outside of the space, and then follow {ref}`matrix-rooms-spaces`. + +1. In the {guilabel}`Name` field, type the display name of the room. + This name can contain upper and lower case characters, spaces, and can be changed later. + +1. The {guilabel}`Topic` field is for the description of your room. + This field is optional and can be filled in later. + +1. In the dropdown, select {guilabel}`Public room`. + +1. In the {guilabel}`Room Address` field, type a room address. + This should be all lower case. + Parts of the name can be separated by using dash characters. + +1. Make sure the address is available, then click on {guilabel}`Create room`. + + +## Room configuration + +### General settings + +After your room is created, click on the room name dropdown on the top of your Element desktop client, and select {guilabel}`Settings`. + +In the "General settings", you can change "Room Name", "Room Topic", and add a "Room Image". +You can also check your published addresses, and local addresses. + +If you cannot enable the {guilabel}`Publish this room to the public in the ubuntu.com's room directory?` toggle, please note this is intended behavior. +Check steps in the {ref}`public-room-publishing` section to complete this task. + + +### Security and privacy settings + +In the {guilabel}`Security & Privacy` settings, you can change your room from Public to Private, or Space members. + +```{warning} +Please **never enable encryption** for public rooms. +You cannot turn it back off, and it creates a lot of issues with public rooms. +``` + + +(public-room-publishing)= +## Room publishing and listing under spaces + +Check {ref}`How to publish and list rooms and spaces ` if you'd like to: + +* Protect your room from abuse +* Publish your room in the server directory +* Add your room to the Ubuntu Community space + + +## Further reading + +Congratulations! Your public room is now ready! +If you would like to learn more about the Ubuntu Matrix homeserver, check {ref}`our documentation `. + diff --git a/docs/community/matrix/room-creation/create-a-public-space.md b/docs/community/matrix/room-creation/create-a-public-space.md new file mode 100644 index 00000000..5ef83d1d --- /dev/null +++ b/docs/community/matrix/room-creation/create-a-public-space.md @@ -0,0 +1,77 @@ +(matrix-space-creation-public)= +# Create and configure a public space + + +This short guide walks you through the creation and basic configuration of a public space on the Ubuntu Matrix homeserver. +This guide assumes you are using the Element desktop client. + +```{note} +A Matrix Space is technically a type of room. +Reference to rooms in this guide are intentional, to stay aligned with the Element client interface. +``` + + +## Create a public space + +1. Click on the {guilabel}`+` icon on the left panel, below your user avatar. + +1. Select {guilabel}`Public`. + +1. In the {guilabel}`Name` field, type the display name of the space. + This name can contain upper and lower case characters, spaces, and can be changed later. + +1. In the {guilabel}`Address` field, type a space address. + This should be all lower case. + Parts of the name can be separated by using dash characters. + +1. In the {guilabel}`Description` field, you can add a description of this space. + This field is optional and can be filled later. + +1. Make sure the address is available, then click {guilabel}`Create`. + +1. In the next screen, you can create rooms within your space. + Click {guilabel}`continue` when ready. + + +## Space configuration + +### General settings + +1. After your space is created, click on the space name drop-down on the left side of your Element desktop client, under the search bar, and select {guilabel}`Settings`. + +1. In the {guilabel}`General` settings, you can change "Name", "Description", and upload an image. + +1. Once all changes are confirmed, select {guilabel}`Save changes`. + + +### Visibility + +In the {guilabel}`Visibility` settings, you can: + +* Change your space from Public to Private, or Space members. + +* Enable or disable space preview. + Keeping this option enabled is recommended for public spaces. + +* Add, remove, or modify local and published addresses. + +* If you cannot enable the {guilabel}`Publish this room to the public in the ubuntu.com's room directory?` toggle, please note this is intended behavior. + Check the steps in the {ref}`public-space-publishing` section to complete this task. + + +(public-space-publishing)= +## Room publishing and listing under spaces + +Please check {ref}`matrix-rooms-spaces` if you'd like to: + +* Protect your space and rooms from abuse. +* Publish your space in the server directory. +* Add your space to the Ubuntu Community space. + + +## Further reading + +Congratulations! Your public space is now ready! +If you would like to learn more about the Ubuntu Matrix homeserver, check {ref}`our documentation `. + + diff --git a/docs/community/matrix/room-creation/index.md b/docs/community/matrix/room-creation/index.md new file mode 100644 index 00000000..8b6615ad --- /dev/null +++ b/docs/community/matrix/room-creation/index.md @@ -0,0 +1,14 @@ +(matrix-room-creation)= +# Matrix room creation + +In this section you will learn how to create and publish rooms and spaces. + +```{toctree} +:maxdepth: 1 + +Create a public room +Create a private room +Create a public space +Create a private space +Publish your room or space +``` diff --git a/docs/community/matrix/room-creation/room-publishing.md b/docs/community/matrix/room-creation/room-publishing.md new file mode 100644 index 00000000..2a25c13f --- /dev/null +++ b/docs/community/matrix/room-creation/room-publishing.md @@ -0,0 +1,32 @@ +(matrix-rooms-spaces)= +# How to publish and list rooms and spaces + +If you have a room that is part of the broader Ubuntu community, you should get it published and added to the Ubuntu Community space (`#community:ubuntu.com`). +If instead you have a collection of rooms for your area or team, please create a space first that groups these rooms. +You can then get your space published and listed into the Ubuntu Community space. + +To publish your public room encryption must be turned off. +There is no advantage in an encrypted public room. +It is not possible to search the room history or configure mentions and keywords in encrypted rooms. + +Please send a message {matrix}`in this room `, asking to add your rooms to the official room list. + +Moderators will perform a few tasks on your room or space: + +1. Add your room or space to the published list. + This will make your room or space searchable in the Ubuntu Matrix instance. + +1. Add your room or space to the **Ubuntu Community** space. + Anyone who joined this space can easily see your room or space. + +1. Invite the moderator bot to your room(s) and change its power level to "Admin". + The bot will grant automated protections. + See [more details on this moderator bot](https://github.com/matrix-org/mjolnir). + + Granting the bot admin rights is necessary for the bot to function properly. + See the {ref}`Official rooms and spaces policy ` for more information. + +1. Add this reminder to the room topic: `Please follow the CoC: https://ubuntu.com/community/ethos/code-of-conduct` + +1. Ensure that room admins understand the expectations and requirements for owning an official Ubuntu Room. + diff --git a/docs/community/matrix/room-ownership/changing-addresses.md b/docs/community/matrix/room-ownership/changing-addresses.md new file mode 100644 index 00000000..10bff9e1 --- /dev/null +++ b/docs/community/matrix/room-ownership/changing-addresses.md @@ -0,0 +1,77 @@ +(matrix-changing-addresses)= +# Change the main address of a room or space + +In this guide, we will change the main address of a room or space to `ubuntu.com`. + +A room or space may have any number of addresses and the main address can be published to the public directory of the homeserver it belongs to for discovery. +Changing and publishing the main address requires changes to be made by a user belonging to the homeserver of that address with power level 50 (moderator) or above. + + +## Quick Guide + +After inviting a user from the `ubuntu.com` homeserver and giving them power level 50+ (moderator), they'll create a local address in settings, set it as the main address and turn on publishing to the homeserver's public directory. + +After that, their privileges can be removed and they don't need to remain (see: {ref}`Caveats `). + + +## Step-by-step guide + + +### As the room/space admin + +1. Invite a trusted Ubuntu user from the `ubuntu.com` homeserver to your room or space. + +1. Set the Ubuntu user's power level to 50 (Moderator) or above. + + +### As an Ubuntu user + +1. Enter the room or space. + +1. Open settings: + + Rooms + : Right-click on the room's icon on the left bar and click {guilabel}`Settings`. + + Spaces + : Click on the name of the space at the top of the left bar just below the {guilabel}`Search` field. + : Click {guilabel}`Settings`. + : Click {guilabel}`Visibility`. + +1. Scroll down until you see the title {guilabel}`Published Addresses` and note the address in the {guilabel}`Main address` drop-down. + If there's no address, ask the admin what they'd like the address to be. + +1. Scroll down until you see the title {guilabel}`Local Addresses` and click {guilabel}`Show more` if applicable. + +1. In the address input field, enter the {guilabel}`Main address` you noted above without the leading `#` or trailing `:ubuntu.com`. + E.g. an address of `#my-room:matrix.org` would be entered as `my-room`. + +1. Click the {guilabel}`Add` button. + +1. Scroll up until you see the title {guilabel}`Published Addresses`, click the {guilabel}`Main address` drop-down and select the new address you added. + You may need to refresh your browser if it's not visible. + + ```{note} + It's important not to delete the local address that's been selected as the main address because it's a pointer to that address, not a copy. + ``` + +1. Toggle the slider next to "Publish this room to the public in ubuntu.com's room directory?" to "On". + You may need to refresh your browser to set it. + + +### As the room/space admin + +Privileges can now be removed from the invited Ubuntu user and they don't need to remain in the room or space (see: {ref}`Caveats `). + + +(matrix-change-address-caveats)= +## Caveats + +* A room or space must have at least one Ubuntu user as a member for it to be visible on the public directory of the `ubuntu.com` homeserver. + +* In {guilabel}`Settings` for rooms, or {guilabel}`Setting > Visibility` for spaces, only an Ubuntu user can see (or toggle with power level 50+) the setting for publishing to `ubuntu.com`'s public directory. + For everyone else it will appear off. + +* Members of any power level can add local addresses or delete the local addresses they've created even if they're in use as the main address. + Care should be taken when relying on addresses that were not created by trusted users though these addresses are easy to replace. + diff --git a/docs/community/matrix/room-ownership/index.md b/docs/community/matrix/room-ownership/index.md new file mode 100644 index 00000000..030dd1f9 --- /dev/null +++ b/docs/community/matrix/room-ownership/index.md @@ -0,0 +1,25 @@ +(matrix-room-config)= +# Matrix room ownership + + +## Room configuration + +```{toctree} +:maxdepth: 1 + +room-properties +recommended-room-settings +Configure room for announcements +``` + + +## Room maintenance + +```{toctree} +:maxdepth: 1 + +Rename or delete a room +Change the main room address +Regain control of a room +``` + diff --git a/docs/community/matrix/room-ownership/recommended-room-settings.md b/docs/community/matrix/room-ownership/recommended-room-settings.md new file mode 100644 index 00000000..097dfe06 --- /dev/null +++ b/docs/community/matrix/room-ownership/recommended-room-settings.md @@ -0,0 +1,75 @@ +(matrix-recommended-room-settings)= +# Recommended room settings + +This article outlines a list of recommended settings for various room types. +If you are looking for specific guides on how to create or configure rooms, check the reference documentation at the bottom of this article. + + +## General advice on admin roles and power levels + +Promoting someone to admin level gives them the highest power level. +They will have full permissions on the room. +It will not be possible to demote them or even remove them from a room in case the room needs to be closed or migrated. +It is generally advisable to select custom power levels and change room permissions to match. +Reach out on the {matrix}`matrix-ops` room if you require assistance. + + +## Public rooms + +### General settings + +* Published addresses should have an address on the Ubuntu homeserver, all lower case, separated by hyphens/dashes if needed, e.g. `#matrix-ops:ubuntu.com`. +* "Publish this room to the public in ubuntu.com's room directory" should be turned on, as outlined in {ref}`matrix-rooms-spaces`. + + +### Security and privacy + +* Encryption: Disabled +* Access: Public +* Who can read history: Anyone + + +## Private rooms + +### General settings + +* Published addresses should have an address on the Ubuntu homeserver, all lower case, separated by hyphens/dashes if needed, e.g. `#matrix-ops:ubuntu.com`. +* "Publish this room to the public in ubuntu.com's room directory" should be turned off. + + +### Security and privacy + +* Encryption: Disabled +* Access: Private +* Who can read history: Members only (since the point in time of selecting this option) + + +## News and announcement rooms + +### General settings + +* Published addresses should have an address on the Ubuntu homeserver, all lower case, separated by hyphens/dashes if needed, e.g. `#matrix-ops:ubuntu.com`. +* "Publish this room to the public in ubuntu.com's room directory" should be turned on, as outlined in {ref}`matrix-rooms-spaces`. + + +### Security and privacy + +* Encryption: Disabled +* Access: Public +* Who can read history: Anyone + + +### Roles and permissions + +* Send Messages: Custom (10) + + +## Further reading + +* {ref}`matrix-room-creation-public` +* {ref}`matrix-room-creation-private` +* {ref}`matrix-space-creation-public` +* {ref}`matrix-space-creation-private` +* {ref}`matrix-room-configuration-announcements` +* {ref}`matrix-rooms-spaces` + diff --git a/docs/community/matrix/room-ownership/regain-control.md b/docs/community/matrix/room-ownership/regain-control.md new file mode 100644 index 00000000..166ab367 --- /dev/null +++ b/docs/community/matrix/room-ownership/regain-control.md @@ -0,0 +1,50 @@ +(matrix-regain-control)= +# How to regain control of a room + +There are several possible scenarios where a room loses its administrator. +To ensure a good experience, we provided a fallback mechanism to all {ref}`public official rooms ` on the Ubuntu homeserver. + + +## Prerequisites + +This guide applies to official rooms on the Ubuntu homeserver that have the Moderator bot invited and properly configured. + +## You are a room admin and lost access to your account + +Access to the Ubuntu Matrix homeserver happens via Single Sign On and is tied to Launchpad groups. +If you cannot login, make sure you recover access to your Launchpad account. +This can be done by accessing the [Launchpad help webpage](https://help.launchpad.net/YourAccount). + + +## The administrators of your room are no longer active + +If you are a room user or moderator, and your room administrator has been inactive for a long period of time: + +**Attempt to reach the room administrator** +: * [Log into Launchpad](https://launchpad.net). +: * In the search bar on the top of the main Launchpad page, type the nickname of the user you are looking for. Launchpad ID is the same as Matrix ID, so if a Matrix user is `@myuser:ubuntu.com`, the Launchpad ID is `myuser`. +: * Check if the user has a separate contact method, and reach out. +: * Note the dates and contacts in case you need to move to the next stage. + +**Reach out to the Matrix Council and ask for help** +: If the room administrator is still not reachable on any alternative platforms after 30 days, or if the room admin has no alternative contacts: +: * Provide the dates when you tried to make contact. +: * Save the matrix ID and Launchpad ID of the administrator you are trying to reach. +: * Draft a message to the Ubuntu Matrix Council with your issue and desired outcome. +: * Send it to the {ref}`Ubuntu Matrix Council `. + + +## Other cases + +If you have a specific case, and you need help: +* For general advice, reach out to the {matrix}`Ubuntu Matrix Ops room `. +* If you need to escalate an issue, contact the {ref}`Ubuntu Matrix Council `. + + +## Further reading + +* {ref}`matrix-room-moderation` +* {ref}`matrix-moderation-and-defense` +* {ref}`matrix-moderator-bot` +* {ref}`matrix-management` + diff --git a/docs/community/matrix/room-ownership/rename-or-delete.md b/docs/community/matrix/room-ownership/rename-or-delete.md new file mode 100644 index 00000000..60f86611 --- /dev/null +++ b/docs/community/matrix/room-ownership/rename-or-delete.md @@ -0,0 +1,54 @@ +(matrix-rename-or-delete)= +# Rename or delete a Matrix room + +If you are thinking about deleting and re-creating a room, in most cases you can adjust settings in a way that you'll get the same end result without recreating the room. + + +## How to rename a room + +Renaming a room will not actually require users to do anything. +The room addresses are simply labels that are applied to the physical room. + +1. Go to {guilabel}`Settings` -- if the room is published, un-publish it from the room directory. + +1. In the {guilabel}`Local Addresses` section, add the new local alias and mark it as "primary". + Then you can remove all aliases that you'd like to get rid of. + + ```{note} + This is a per-homeserver setting, so if you have an `:ubuntu.com` account, you can only add/remove `:ubuntu.com` aliases. + If you'd like to add/remove an alias on a different homeserver like `matrix.org`, get a room admin with an account on that server to do it. + ``` + +1. If you've changed the main address, promote the new main address for the room. + +1. If the room was previously published, you can publish it again. + Note that if you change the homeserver suffix in the main address, it will be published to that homeserver instead. + + +## How to delete a room + +1. Go to {guilabel}`Settings` + +1. Un-publish the room from the room directory. + An admin with an account on the homeserver of the main room address needs to do this. + +1. Remove all local aliases for the room, across all homeservers + +1. In {guilabel}`Room settings` -> {guilabel}`Security & Privacy` -> {guilabel}`Access`, select {guilabel}`Private (invite only)` + +1. Kick everyone out that you can. + You can't kick out people at the same permissions level as you; these folks will have to leave or demote themselves. + +1. Take a final look to see if everything is clean and close the door behind you. + + +### How to redirect people to another room + +1. The simple version is to invite them to the new room and then shut down the old room using the steps above. + +1. The hard version involves sending a so-called "tombstone event". + This requires a command-line client or using CURL requests with your token. + While this event is usually meant for room upgrades, it can also be used to determine a new room where the conversation continues. + There are guides on how to do this on the internet. + Be careful, you don't want to lose everyone in the room! + diff --git a/docs/community/matrix/room-ownership/room-configuration-announcements.md b/docs/community/matrix/room-ownership/room-configuration-announcements.md new file mode 100644 index 00000000..88c4f84c --- /dev/null +++ b/docs/community/matrix/room-ownership/room-configuration-announcements.md @@ -0,0 +1,46 @@ +(matrix-room-configuration-announcements)= +# How to configure a room for announcements + +You might want to have dedicated rooms in your space dedicated to announcements, news, feeds, or a mix of the three. +There are many bots that pull information from other platforms, such as social media, news sites, Launchpad, GitHub, GitLab, and many more. +However, a room admin usually wants to focus discussions in specific channels: + +* To avoid chatter mixed with news and important announcements making everything hard to find +* To keep important announcements visible to your community for a longer period of time + + +## Configure your room + +1. First, {ref}`create a public ` or {ref}`a private room ` + +1. Select a suitable name and topic for your room, so the community knows what to expect + +1. Right click on the room name, and select {guilabel}`Settings` + +1. Select the {guilabel}`Roles & Permissions` menu + +1. In the {guilabel}`Permissions` section, open the {guilabel}`Send Messages` drop-down menu + +1. Change the setting from {guilabel}`Default` to {guilabel}`Custom level`, and type 10 + +1. Close the {guilabel}`Settings` menu + + +## Configure user power level + +Users or bots need at least power level 10 to post messages in this room. +This gives room administrators good flexibility to let users or bots post messages, without having to promote them to mods or admins. + +1. Right click on the room name, and select {guilabel}`People` + +1. Select the user or bot you want to allow to send messages in this room + +1. Check their power level; if it is {guilabel}`Default` and you do not want to grant mod or admin status, click the {guilabel}`Power level` drop-down menu and select {guilabel}`Custom level` + +1. Enter 10 in the {guilabel}`Power level` drop-down + + +## Further reading + +* {ref}`matrix-moderation-and-defense` + diff --git a/docs/community/matrix/room-ownership/room-properties.md b/docs/community/matrix/room-ownership/room-properties.md new file mode 100644 index 00000000..f533bbcf --- /dev/null +++ b/docs/community/matrix/room-ownership/room-properties.md @@ -0,0 +1,40 @@ +(matrix-room-properties)= +# Room properties + +**Room name** +: * Your room name should stand for itself and accurately describe its purpose. +: * It can use more than one word and does not need to be lowercase-in-one-word-with-dashes like on IRC, however keep it concise so people will understand at a glance. + +**Room topic** +: * This is the topic at the top of the room, what people need to know who just arrived or are a part of the room. +: * While (currently) Markdown is not supported, you can use links which will automatically link in Element's clients and others. +: * Start with a short sentence on what is to be discussed, then link off to a page that describes your effort in more detail. + +**Room addresses** +: * Matrix rooms don't *only* exist on the server you are on; thanks to federation, they are synchronized between all servers of everyone participating. So there is no concept of "A room on the :ubuntu.com server" aside from the fact that it might have been created there. +: * Each room has a "main address" where it is considered home. Additionally, rooms can have an alias on any number of other servers. Adding an alias needs to be done by an admin to your room with an account on the respective other server. +: * As a matter of convention, please use all lowercase for the room aliases. If you are organizing your rooms as part of a space, stay consistent. For example, in the Charmhub Space, the Identity team might have its own space, and there are a set of rooms including a general room. You'd have #charmhub-identity-general:ubuntu.com as your alias. +: * Even if your room is part of a space, please remember that a room can be joined by people that have not joined the space it is listed in. Therefore, please make sure that room alias gives enough context to people that look it up or join: +: * Bad example: `#general-chatter:ubuntu.com` +: * Good example: `#kubuntu-general-chatter:ubuntu.com` +: * If you are moving a room, you don't need to re-create it. You can simply remove and add the aliases accordingly, and the room will continue to exist in its new location with everyone in it. + + +## Security and privacy + +**General hints** +: * "Block anyone not part of ubuntu.com from ever joining this room", or disabling federation, should generally not be used. It may make sense for a very limited set of rooms, e.g. a room only for Ubuntu Members. Note for Canonical, this is not a way to restrict communications to just Canonical staff. +: * If you create a room encrypted or with federation blocked, you will not be able to change this if you decide differently later. You can however migrate people to the new room, but it requires an interaction from them. Keep this in mind especially when creating private rooms you think might become public soon. + +**Public rooms** +: * Public rooms should not be encrypted, as this complicates the setup for a room that is open for anyone to join anyway. +: * For public rooms please keep the default history setting of "Members only (since the point in time of selecting this option)". For select public rooms we may expand this to "Anyone", but please discuss with moderators beforehand. + +**Space members** +: * This setting mainly makes sense for private spaces, so that people who have been invited to the space can join any room in the space. +: * For public spaces, please don't use this option. + +**Private rooms** +: * Use these for truly private conversations where you don't expect community members to join. +: * The history setting "Members only (since they were invited)" will allow you to give people context between when you invite them and when they join. + diff --git a/docs/contributors/index.md b/docs/contributors/index.md index e75c9672..ab280151 100644 --- a/docs/contributors/index.md +++ b/docs/contributors/index.md @@ -110,6 +110,18 @@ Contribute docs ``` +## Setting up and using Matrix + +Matrix is the instant messaging platform the Ubuntu Community uses. +This section will help you get set up with a Matrix client and show you how to use it to stay in contact with the community. + +```{toctree} +:maxdepth: 1 + +/community/contributors/matrix/index +``` + + ## Advanced tasks Although you do not need any elevated permissions to work on the tasks in this @@ -122,6 +134,7 @@ some working familiarity with Ubuntu development. Advanced tasks ``` + ## Mirrors ```{toctree} diff --git a/docs/maintainers/index.md b/docs/maintainers/index.md index e556a3b4..b7178e18 100644 --- a/docs/maintainers/index.md +++ b/docs/maintainers/index.md @@ -8,6 +8,14 @@ frequency (i.e. most common tasks first) These guides are for those with elevated permissions on particular tasks who are responsible for maintaining the Package Archive or managing processes. +## Matrix management + +```{toctree} +:maxdepth: 1 + +/community/matrix/index +``` + ## Uploader tasks ```{toctree}