Merge branch '890-docs' into 'develop'

See #890: Documentation and release notes

Closes #890

See merge request funkwhale/funkwhale!886

changes/changelog.d/890.feature

@@ -0,0 +1 @@
+Content and account reports (#890)

changes/notes.rst

@@ -32,6 +32,22 @@ Tags are used in various places to enhance user experience:
 If you are a pod admin and want to extract tags from already uploaded content, you run `this snippet <https://dev.funkwhale.audio/funkwhale/funkwhale/snippets/43>`_
 and `this snippet <https://dev.funkwhale.audio/funkwhale/funkwhale/snippets/44>`_ in a ``python manage.py shell``.
 
+Content and account reports
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is now possible to report content, such as artists, tracks or libraries, as well as user accounts. Such reports are forwarded to the pod moderators,
+who can review it and delete reported content, block accounts or take any other action they deem necessary.
+
+By default, both anonymous and authenticated users can submit these reports. This makes sure moderators can receive and handle
+takedown requests and other reports for illegal content that may be sent by third-parties without an account on the pod. However,
+you can disable anonymous reports completely via your pod settings.
+
+Federation of the reports will be supported in a future release.
+
+For more information about this feature, please check out our documentation:
+
+-  `User documentation <https://docs.funkwhale.audio/moderator/reports.html>`_
+-  `Moderator documentation <https://docs.funkwhale.audio/users/reports.html>`_
 
 
 Allow-list to restrict federation to trusted domains
@@ -79,11 +95,11 @@ To improve the security and reduce the attack surface in case of a successfull e
 you add the following Content-Security-Policy to your nginx configuration.
 
 ..note::
-    
+
     If you are using an S3-compatible store to serve music, you will need to specify the URL of your S3 store in the ``media-src`` and ``img-src`` headers
 
     .. code-block::
-    
+
         add_header Content-Security-Policy "...img-src 'self' https://<your-s3-URL> data:;...media-src https://<your-s3-URL> 'self' data:";
 
 **On non-docker setups**, in ``/etc/nginx/sites-available/funkwhale.conf``::

docs/moderator/index.rst

@@ -2,7 +2,7 @@ Moderator Documentation
 =========================
 
 This documentation is targeted at instance moderators. Moderators have enhanced permissions
-which allow them to moderate federated accounts and domains.
+which allow them to handle reports and moderate federated accounts and domains.
 
 Moderation Guides
 -----------------
@@ -10,7 +10,7 @@ Moderation Guides
 .. toctree::
    :maxdepth: 2
 
+   reports
    domains
    users
    listing
-

docs/moderator/reports.rst

@@ -0,0 +1,44 @@
+Handling user reports
+=====================
+
+:doc:`Users can submit reports </users/reports>` in various places. When they do so,
+their report ends up in a moderation queue until it is reviewed and resolved by a moderator.
+
+View unresolved reports
+-----------------------
+
+Assuming you have the moderation permission, you'll find a "Moderation" link in the sidebar.
+
+Clicking on this link will bring you to the list of unresolved reports. For convenience,
+the number of unresolved reports (if any) is also displayed directly next to this link, and updated in real time
+when new reports are submitted.
+
+Email notifications
+-------------------
+
+In addition to the web UI, all moderators will receive a notification email whenever a report is 
+submitted or resolved providing your pod has a valid email sending configuration. 
+This notification will include a link to review and handle the report, as well as additional 
+information about the report itself.
+
+Handling reports
+----------------
+
+When viewing the moderation queue, you will be presented with the list of unresolved reports.
+
+Each report in the queue should include all the information you need to handle it, in particular:
+
+- Who submitted the report (or the email adress of the submitter if it's an accountless report)
+- The report content
+- A link to the reported object, and a copy of this object data at the time the report was submitted
+
+When you mark a report as resolved, the report will simply be removed from the queue, and you can proceed to the next one.
+
+Doing so will also assign the report to you, so other moderators can see who handled a given report.
+
+Internal Notes
+--------------
+
+Whenever you need to perform an action because of a report, you can use the included form to leave a note to other moderators, or even yourself, for reference.
+
+These notes are viewable by instance admins and moderators only.

docs/users/index.rst

@@ -28,6 +28,7 @@ Using Funkwhale
    radios
    follow
    apps
+   reports
 
 Troubleshooting Issues
 ----------------------

docs/users/reports.rst

@@ -0,0 +1,54 @@
+Reporting content and accounts
+==============================
+
+Funkwhale includes a report feature you can use to contact your pod's moderators.
+
+If you think some action, such as removal, should be taken toward an account or specific content (like an artist or a library), we encourage you to use
+this feature. This is especially recommended if you find illegal or abusive content, or anything that could be an infraction of your pod's rules.
+
+After submission, your pod moderators will be notified and will be able to :doc:`act on your report </moderator/reports>`.
+
+Submit a report
+---------------
+
+You can submit those reports from various places in the app, depending on what you are reporting (see below).
+
+You'll need to pick a category for your report. Available categories are:
+
+- **Takedown request**: to request removal of copyrighted material
+- **Illegal content**: to report an account, track, album, artist, library, playlist or account that features illegal content
+- **Offensive content**: to report an account, track, album, artist, library, playlist or account that features offensive or abusive content
+- **Invalid metadata**: to report a track, album or artist with invalid or incomplete metadata
+- **Other**: to report anything else that doesn't fit into one of these categories
+
+You can also include with your report an additional explanation to ensure moderators can understand and act on the issue.
+
+Accountless reports
+-------------------
+
+If this feature is enabled on the pod you are browsing, you'll be able to submit reports without an account.
+
+This works exactly the same, but the report form will have an extra "email" field where you should include a working
+email address, in the event moderators need to contact you.
+
+Reporting an account
+--------------------
+
+Accounts can be reported in two ways.
+
+- When viewing user activity, such as favorites or listening history, the dropdown menu next to the corresponding activity will include an option to report the account
+- When viewing a library the dropdown menu in the top right corner will include an option to report the corresponding account
+
+Reporting an artist, playlist, album or track
+---------------------------------------------
+
+Anything you can play can typically be reported using the dropdown menu on the "Play" button.
+
+Additionally, when viewing the detail page of an artist, playlist, album or track, you can find the
+report option under the dropdown menu on the "More…" button.
+
+
+Reporting a library
+-------------------
+
+When viewing a library the dropdown menu in the top right corner will include an option to report the library.