From df32a482c14cce1051f28c865f8b18d57ace2ad4 Mon Sep 17 00:00:00 2001 From: Emelia Smith Date: Wed, 18 Sep 2024 01:45:47 +0200 Subject: [PATCH] Fix langauge around producers vs providers, adding a Definitions section --- docs/.vitepress/config.ts | 29 +++++++++++++++---- .../background/goals-and-objectives.md | 15 +++++----- .../concepts/background/historical-context.md | 4 +-- docs/concepts/background/index.md | 6 +++- docs/concepts/terms/data-consumer.md | 8 +++++ docs/concepts/terms/data-provider.md | 12 ++++++++ docs/concepts/terms/label-provider.md | 8 +++++ .../index.md | 2 +- 8 files changed, 67 insertions(+), 17 deletions(-) create mode 100644 docs/concepts/terms/data-consumer.md create mode 100644 docs/concepts/terms/data-provider.md create mode 100644 docs/concepts/terms/label-provider.md rename docs/manuals/{example-publisher => example-provider}/index.md (79%) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 19936db..918621f 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -9,7 +9,7 @@ export default defineConfig({ message: 'Released under the AGPL License.', copyright: - 'Copyright © 2024 FediMod FIRES Project', + 'Copyright © 2024 FediMod FIRES Project', }, // https://vitepress.dev/reference/default-theme-config @@ -26,8 +26,8 @@ export default defineConfig({ link: "/manuals/reference-server/", }, { - text: "Example Publisher", - link: "/manuals/example-publisher/", + text: "Example Provider", + link: "/manuals/example-provider/", }, { text: "Example Consumer", @@ -55,6 +55,23 @@ export default defineConfig({ { text: "Retractions", link: "/concepts/retractions" }, ], }, + { + text: "Definitions", + items: [ + { + text: "Data Provider", + link: "/concepts/terms/data-provider", + }, + { + text: "Data Consumer", + link: "/concepts/terms/data-consumer", + }, + { + text: "Label Provider", + link: "/concepts/terms/label-provider", + }, + ], + }, { text: "Project Background", items: [ @@ -114,13 +131,13 @@ export default defineConfig({ ], }, ], - "/manuals/example-publisher": [ + "/manuals/example-provider": [ { - text: "Example Publisher", + text: "Example Provider", items: [ { text: "Introduction", - link: "/manuals/example-publisher/", + link: "/manuals/example-provider/", }, ], }, diff --git a/docs/concepts/background/goals-and-objectives.md b/docs/concepts/background/goals-and-objectives.md index 11cceed..1cb9cfb 100644 --- a/docs/concepts/background/goals-and-objectives.md +++ b/docs/concepts/background/goals-and-objectives.md @@ -1,24 +1,25 @@ # Goals & Objectives -This proposal aims to develop a small server that can be integrated with by Data Providers allowing them to publish moderation advisories and recommendations via an API that allows for resumable consumption of the data, with the full changelog of the data being made available by the server. The data made available by this server is designed to be structured data, suitable for machine consumption, allowing it to be surfaced via tools and user interfaces. +This proposal aims to develop a small server that can be integrated with by [Data Providers](../terms/data-provider) allowing them to publish moderation advisories and recommendations via an API that allows for resumable consumption of the data, with the full changelog of the data being made available by the server. The data made available by this server is designed to be structured data, suitable for machine consumption, allowing it to be surfaced via tools and user interfaces. Data Providers are individuals, groups, or organisations who currently maintain denylists, conduct & publish threat intelligence research, or handle other matters related to coordinating and improving the trust and safety of the fediverse. -We take the stance that consumers (instance operators or end-users) of the information published to the server by Data Providers (see below) should ultimately decide which moderation action to take in response to the data published. +We take the stance that consumers (instance operators or end-users) of the information published to a FIRES server by [Data Providers](../terms/data-provider) should ultimately decide which moderation action to take in response to the data published. -In more definitive terms: **this proposed server only** **provides moderation advisories and recommendations, rather than prescribing that a given action must be taken**. This is in contrast to the current status quo with denylists which are very prescriptive about what action must be taken. +In more definitive terms: **FIRES only provides moderation advisories and recommendations, rather than prescribing that a given action must be taken**. This is in contrast to the current status quo with denylists which are very prescriptive about what action must be taken. -**This server is not designed for creation of denylists**, and although you could use it for that purpose, the intended way of using the data is not through bulk automated imports of data, instead we encourage instance operators to review the data contained and to make their own decisions based upon the data. +**FIRES is not designed for creation of denylists**, and although you could use it for that purpose, the intended way of using the data is not through bulk automated imports of data, instead we encourage instance operators to review the data contained and to make their own decisions based upon the data. -**This proposal is not for a centralised service**, but instead it is designed to be hosted by data providers who then integrate with it to supply their data to downstream consumers. Whether those providers are providing data to reduce illegal content, racism, transphobia, or other bigotry is entirely up to them, and how they source & manage their data is entirely up to them. +**FIRES is not for a centralised service**, but instead it is designed to be hosted by data providers who then integrate with it to supply their data to downstream [consumers](../terms/data-consumers). Whether those providers are providing data to reduce illegal content, racism, transphobia, or other bigotry is entirely up to them, and how they source & manage their data is entirely up to them. Other software should integrate with the server and consume the published data, handling the application of advisories and recommendations to downstream instances, ideally with a workflow that actively involves the instance operator. For instance, software _could_ be written to selectively apply recommendations based on configured needs using the labels associated with the moderation advisories or recommendations, adjusting the acceptance of recommended actions and filters as necessary for that consumer. Software _could_ also be written to allow downstream consumers to decide to implicitly trust & accept the recommendations provided and apply the actions and filters recommended automatically, even though this is discouraged. -_Software Implementer Note: If downstream software chooses to apply their own rulings based on the data, then they should ensure that any changes published with the recommended_action of “none” or that have a type of “retraction” should have them re-evaluate their rulings, as these are **retractions of a previous advisory or recommendation**._ +> [!WARNING] Software Implementer Note +> If downstream software chooses to apply their own rulings based on the data, then they should ensure that any changes published with the `recommended_action` of “none” or that have a type of “retraction” should have them re-evaluate their rulings, as these are **retractions of a previous advisory or recommendation**. -**The server is also not designed to be a user-facing website or application**, instead it is a tool that data providers can integrate with to simplify the change tracking and distribution of their moderation recommendations and advisories. The only optional component that can be user-facing is the labels website, but we also encourage you to proxy or host this directly via your platform for moderation recommendations. +**FIRES is also not designed to be a user-facing website or application**, instead it is a tool that data providers can integrate with to simplify the change tracking and distribution of their moderation recommendations and advisories. The only optional component that can be user-facing is the [Label Provider](../terms/label-provider), but we also encourage you to proxy or host this directly via your platform for moderation data. This is in contrast with existing domain denylists and how they are distributed, which are highly prescriptive: “you must block this domain because we say”. Generally, there is no mechanism through which to reject a denylists’ rulings as you lack the information to help you decide and fediverse tooling often doesn’t provide you a choice, unless you manually edit the CSV file by hand or pre-process it in some way, which as noted can be difficult based on the lack of data presented in existing denylists. diff --git a/docs/concepts/background/historical-context.md b/docs/concepts/background/historical-context.md index 2404c9e..e88c8e8 100644 --- a/docs/concepts/background/historical-context.md +++ b/docs/concepts/background/historical-context.md @@ -8,13 +8,13 @@ Additionally, these CSV files have a maximum row count of 20,000 rows when impor [Pixelfed](https://pixelfed.org/), [Misskey](https://misskey-hub.net/en/), [Mbin](https://joinmbin.org/) and [Lemmy](https://join-lemmy.org/) all currently do not support importing denylists of domain blocks using the Mastodon formatted CSV files, but they do feature their own ways for managing instance-level domain blocks. Some of these projects do have APIs for managing domain blocks, though these are usually only available on a per-user basis rather than instance-wide, and the instance-wide options are often via a single “config” value, rather than properly structured models representing federation management. -**Pixelfed** does support importing a dataset of instances from a custom formatted JSON document in their admin panel, and offers [a tool for converting](https://dansup.github.io/masto2pixel/) between the Mastodon CSV file format and the Pixelfed JSON document format. +**Pixelfed** does support importing a dataset of instances from a custom formatted JSON document in their admin panel, and offers [a tool for converting](https://dansup.github.io/masto2pixel/) between the Mastodon CSV file format and the Pixelfed JSON document format. Pixelfed is [reportedly working](https://mastodon.social/@dansup/112982425034464618) on improved federation management. **Misskey, Mbin, and Lemmy** all only support a new line delimited list of domains which should be blocked from federation, without the nuance that not everything needs to be defederated completely and losing the context of “why” something was blocked. These CSV-based lists are also generally distributed via code hosting services such as GitHub and Codeberg, or via just CSV file downloads from a data provider’s website, which means that they are point-in-time snapshots. This means that to figure out the changes to a list over time, you must manually diff between two copies of the list, or look at version control histories. -Often the _“why”_ behind changes is difficult to determine, given the unstructured text fields are the only means through which to communicate the _“why”_ and you’re relying on diffs of CSV files. +Often the _“why”_ behind changes is difficult to determine, given the unstructured text field for public comments are the only means through which to communicate the _“why”_ and you have to rely on diffs of CSV files to see what changed. Additionally, as they are lists of instances to block federation with, it is important to note that many providers of denylists [have made mistakes](https://seirdy.one/posts/2023/05/02/fediverse-blocklists/#mistakes-made), and these mistakes can often cause irreparable damage when lists are imported with implicit trust that the data contained within is accurate, and when [retraction lists cannot easily be imported](https://github.com/mastodon/mastodon/issues/25261) into software. diff --git a/docs/concepts/background/index.md b/docs/concepts/background/index.md index ba3b187..a48988a 100644 --- a/docs/concepts/background/index.md +++ b/docs/concepts/background/index.md @@ -21,4 +21,8 @@ Very commonly, the reason for a domain block is not provided, or if it is provid Various attempts have been made at improving denylists, however, fundamentally these denylists represent an all-or-nothing and very harsh approach to managing federation with other instances, and the act of creating a domain block in itself isn’t a strong enough signal about an instance/domain. -Denylists are also only at the level of instance federation, and lack support for sharing moderation information at a more granular level. This can result in entire instances being added to denylists for the actions of a few, rather than sharing information about moderating specifically those harmful users. Sharing moderation information on specific actors/users will become increasingly important in an ever growing fediverse with the likes of [Meta’s](https://about.meta.com/) [Threads](https://threads.net) and [Wordpress.com](https://wordpress.com) joining the fediverse.. +Denylists are also only at the level of instance federation, and lack support for sharing moderation information at a more granular level. This can result in entire instances being added to denylists for the actions of a few, rather than sharing information about moderating specifically those harmful users. + +Sharing moderation information on specific actors/users will become increasingly important in an ever growing fediverse with the likes of [Meta’s](https://about.meta.com/) [Threads](https://threads.net) and [Wordpress.com](https://wordpress.com) joining the fediverse.. + +**FediMod FIRES is designed to support a wide range of moderation data, not just domains, but also actors, hashtags, urls, and more.** There's no reason that the moderation data that we share in the fediverse has to be limited to bad domains. diff --git a/docs/concepts/terms/data-consumer.md b/docs/concepts/terms/data-consumer.md new file mode 100644 index 0000000..a95cb2b --- /dev/null +++ b/docs/concepts/terms/data-consumer.md @@ -0,0 +1,8 @@ +# Data Consumer + +> [!CAUTION] +> This section of the documentation is still being written. + +A **Data Consumer** is any application or software that consumes data from a FIRES server. + +For example, a data consumer may automate the API interactions with Fediverse software for creating, updating, and removing domain blocks using the changes to [Domain Entities](#). diff --git a/docs/concepts/terms/data-provider.md b/docs/concepts/terms/data-provider.md new file mode 100644 index 0000000..592bdba --- /dev/null +++ b/docs/concepts/terms/data-provider.md @@ -0,0 +1,12 @@ +# Data Provider + +> [!CAUTION] +> This section of the documentation is still being written. + +A **Data Provider** is typically a web application that sits in front of a FIRES server and manages the data within it. They may also be command line tools, though these are typically less user friendly. + +The [Example Provider](/manuals/example-provider/) being built is designed to source domain blocks from a collection of Fediverse servers, aggregating and pushing different sets of domains to a FIRES server based on consensus percentage. + +A more advanced Data Provider might source a variety of data from Fediverse servers and other data sources, and provide a communal voting system for deciding which data to push to a FIRES server that the community runs. + +**Data Providers** are typically individuals, groups, or organisations who maintain a set of moderation data, conducting threat intelligence research and handling other matters related to coordinating and improving the trust and safety of the fediverse. diff --git a/docs/concepts/terms/label-provider.md b/docs/concepts/terms/label-provider.md new file mode 100644 index 0000000..15bb03b --- /dev/null +++ b/docs/concepts/terms/label-provider.md @@ -0,0 +1,8 @@ +# Label Provider + +> [!CAUTION] +> This section of the documentation is still being written. + +A **Label Provider** maintains a collection of [labels](../labels) and publishes these as both a website and linked data dataset via content negotiation. + +**Label Providers** are not necessarily [Data Providers](./data-provider), the two are separate as to encourage different Data Providers to reuse pre-existing labels for their moderation data. diff --git a/docs/manuals/example-publisher/index.md b/docs/manuals/example-provider/index.md similarity index 79% rename from docs/manuals/example-publisher/index.md rename to docs/manuals/example-provider/index.md index 80c96bd..5d48dcd 100644 --- a/docs/manuals/example-publisher/index.md +++ b/docs/manuals/example-provider/index.md @@ -1,4 +1,4 @@ -# Example Producer +# Example Provider > [!CAUTION] > This section of the documentation is still being written.