From c1cb3e8dff167c896c30795f8f22c103e8b2f942 Mon Sep 17 00:00:00 2001 From: Gnuxie <50846879+Gnuxie@users.noreply.github.com> Date: Wed, 15 Jan 2025 22:59:01 +0000 Subject: [PATCH] Update README for 2.0.0. (#676) * Update README for 2.0.0. * Mjolnir link. Thanks to feedback from @mahdi1234. * Update antispam plugin link. * Typo in sentance Thanks to @ll-SKY-ll for spotting meow. --- README.md | 128 +++++++++++++++++++++++++++++------------------------- 1 file changed, 69 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index d6fbaf78..634b4ffa 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,9 @@ for installation instructions and usage guides. ## Features +Draupnir's UX is centred around prompting you with questions to carry out +specific moderation tasks by shadowing the actions taken by your Matrix Client. + Draupnir has two main functions, the first is to synchronise bans for users and servers across all of the matrix rooms that you moderate. The second is to protect your community by applying policies from community curated policy lists, @@ -24,15 +27,47 @@ for example the to your rooms around the clock. This means that communities can warn and protect each other of known threats. -Draupnir also includes a series of protections that can be enabled that might -help you in some scenarios. +Draupnir and the list provided by the community moderation effort are the bread +and butter essentials of moderating public spaces on Matrix. -By default Draupnir includes support for user bans, redactions and server ACLs. +Draupnir also includes a series of protections that can be enabled that can help +you in given scenarios when your community is being targeted. Some support is also provided for server administrative functions, such as reviewing abuse reports, deactivating user accounts and shutting down rooms. +However, Draupnir is primarily a room moderation bot and can be used without +server administrative capabilities. + +**Draupnir is a forwards and backwards compatible drop in replacement for +[Mjolnir](https://github.com/matrix-org/mjolnir)**. + +### Prompt UX + +The main difference from Mjolnir is that it is no longer necessary to use +commands for some functions. Banning a user in a protected room from your Matrix +client will cause Draupnir to show a prompt in the management room, which will +offer to add the ban to a policy list[^the-gif-width]. + +![A demo showing a propagation prompt](docs/ban-propagation-prompt.gif) + +You can also unban users the same way, and Draupnir will prompt you to unban +them without any confusing hiccups. If you do still wish to use the ban command, +please note that users and other entities that are being banned are now the +first argument to the ban command. It is now also possible to provide only the +entity to Draupnir and have Draupnir prompt you for the policy list and the ban +reason. + +![A demo showing the ban command](docs/ban-command-prompt.gif) + +In general, all commands have been migrated to a new interface which feature +better error messages for common problems and allow admins to trace the cause of +unexpected errors much more easily. + +[^the-gif-width]: + Yes, i know they don't align horizontally, you are welcome to suggest how + this should be fixed. -### Differences from Mjolnir +### Technical differences from Mjolnir and other moderation bots > I offer you the ring, which was burned, laid upon the pyre of Baldr by Odin. @@ -41,29 +76,35 @@ in order to radically refactor the code base and break a feature freeze. Draupnir has now completed this refactor and large sections of the the code base are now very distinct, as much of Draupnir was rewritten. -Draupnir remains a drop in replacement for Mjolnir and is forwards and backwards -compatible. - -#### Changes in `v2.0.0-beta.*` (pre-release) - -- Draupnir's new core efficiently caches room state and room membership allowing - Draupnir to be much more responsive than Mjolnir. +**Draupnir remains a forwards and backwards compatible drop in replacement for +Mjolnir**. - Draupnir is much less dependant on commands and will automatically send prompts to the management room. Prompts are sent for inviting Draupnir to protect rooms, watch policy lists, ban users, and unban users. +- Draupnir is much more responsive. Unlike Mjolnir and other bots, Draupnir does + not need to request any data from the homeserver before applying new bans or + to ban new users. + +- Draupnir uses an advanced persistent revision system for room state, members, + policies, and policy matches. By using revisions, Draupnir only has to process + room state once in terms of simple deltas as room state is updated. + - Draupnir offers a [room state backing store](https://github.com/the-draupnir-project/Draupnir/blob/main/config/default.yaml#L206-L212), - allowing Draupnir startup quickly, even when deployed at distance from the + allowing Draupnir to startup quickly, even when deployed at distance from the homeserver. - Draupnir's core functionality is implemented as protections, which can be - dynamically turned on and off. - -- Most effort has been spent refactoring the code base, paving the way for - future feature development and adjacent projects. This includes the rewrite of - the core of Draupnir into the + configured and dynamically turned on and off. If you can write even a little + JS/TS, Draupnir's behaviour can be radically changed or customized. And + because the core functionality is implemented with the extension system, there + are less limits. + +- A huge effort has been spent refactoring the code base, paving the way for + future feature development of Draupnir and adjacent projects. This includes + the rewrite of the core of Draupnir into the [matrix-protection-suite](https://github.com/Gnuxie/matrix-protection-suite), providing all the Matrix client code required to operate a protection platform. The @@ -77,51 +118,13 @@ compatible. [typescript-eslint](https://typescript-eslint.io/) into Draupnir's development tooling, modernising TypeScript development. -#### Changes in latest `v1.87.0` - -The main difference from Mjolnir is that it is no longer necessary to use -commands for some functions. Banning a user in a protected room from your Matrix -client will cause Draupnir to show a prompt in the management room, which will -offer to add the ban to a policy list[^the-gif-width]. - -![A demo showing a propagation prompt](docs/ban-propagation-prompt.gif) - -You can also unban users the same way, and Draupnir will prompt you to unban -them without any confusing hiccups. If you do still wish to use the ban command, -please note that users and other entities that are being banned are now the -first argument to the ban command. It is now also possible to provide only the -entity to Draupnir and have Draupnir prompt you for the policy list and the ban -reason. - -![A demo showing the ban command](docs/ban-command-prompt.gif) - -In general, all commands have been migrated to a new interface which feature -better error messages for common problems and allow admins to trace the cause of -unexpected errors much more easily. - -[^the-gif-width]: - Yes, i know they don't align horizontally, you are welcome to suggest how - this should be fixed. - ## Status Draupnir is being supported with a grant from NLnet, the goals of the work are described [here](https://marewolf.me/posts/draupnir/24-nlnet-goals.html) -Currently The UX and code base of Draupnir has been overhauled and Draupnir is -moving towards a 2.0.0 release. - -As Draupnir heads towards `v2.0.0`, releases will appear -[here](https://github.com/Gnuxie/Draupnir/releases). Until `v2.0.0` there will -be frequent changes to commands but all of these will be noted in the changes -for that release. - -Currently, we are running a beta channel (`v2.0.0-beta.*`). As of now all -functionality apart from dynamic configuration of protection settings is stable -in the beta channel. - -For the latest stable release, see `v1.87.0`, the documentation for which can be -found [here](https://github.com/the-draupnir-project/Draupnir/tree/v1.87.0). +Currently The UX and code base of Draupnir has been overhauled and we have +recently passed a huge milestone: Draupnir's 2.0.0 release. ### Migration @@ -143,8 +146,9 @@ for first-time setup documentation. See the [configuration sample with documentation](config/default.yaml) for detailed information about Draupnir's configuration. -See the [synapse module documentation](docs/synapse_module.md) for information -on how to setup Draupnir's accompanying Synapse Module. +See the +[synapse module documentation](https://the-draupnir-project.github.io/draupnir-documentation/bot/synapse_module) +for information on how to setup Draupnir's accompanying Synapse Module. ## Quickstart guide @@ -198,6 +202,12 @@ feature. Also, you should probably setup your `production.yaml` to ensure that the web server can only receive requests from your reverse proxy (e.g. `localhost`). +### Legacy documentation (`v1.87.0` and below) + +For information about the legacy version of Draupnir, see `v1.87.0`, the +documentation for which can be found +[here](https://github.com/the-draupnir-project/Draupnir/tree/v1.87.0). + ## Contributing & Opening Issues Draupnir wants to be yours as much as it is ours. Please see or