From aee792ab478dda746feafe69dc0ed963cb48c7b5 Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Fri, 18 May 2018 22:13:33 +0200
Subject: [PATCH] Fix #152: changelog and documentation

---
 changes/changelog.d/152.feature | 32 ++++++++++++++++++++++++++++++++
 docs/configuration.rst          | 25 +++++++++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 changes/changelog.d/152.feature

diff --git a/changes/changelog.d/152.feature b/changes/changelog.d/152.feature
new file mode 100644
index 000000000..a10225288
--- /dev/null
+++ b/changes/changelog.d/152.feature
@@ -0,0 +1,32 @@
+Simpler permission system (#152)
+
+
+Simpler permission system
+=========================
+
+Starting from this release, the permission system is much simpler. Up until now,
+we were using Django's built-in permission system, which was working, but also
+quite complex to deal with.
+
+The new implementation relies on simpler logic, which will make integration
+on the front-end in upcoming releases faster and easier.
+
+If you have manually given permissions to users on your instance,
+you can migrate those to the new system.
+
+On docker setups:
+
+.. code-block:: shell
+
+    docker-compose run --rm api python manage.py script django_permissions_to_user_permissions --no-input
+
+On non-docker setups:
+
+.. code-block:: shell
+
+    # in your virtualenv
+    python api/manage.py script django_permissions_to_user_permissions --no-input
+
+There is still no dedicated interface to manage user permissions, but you
+can use the admin interface at ``/api/admin/users/user/`` for that purpose in
+the meantime.
diff --git a/docs/configuration.rst b/docs/configuration.rst
index b7df2db42..46756bb26 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -117,3 +117,28 @@ Then, the value of :ref:`setting-MUSIC_DIRECTORY_SERVE_PATH` should be
 On non-docker setup, you don't need to configure this setting.
 
 .. note:: This path should not include any trailing slash
+
+User permissions
+----------------
+
+Funkwhale's permission model works as follows:
+
+- Anonymous users cannot do anything unless configured specifically
+- Logged-in users can use the application, but cannot do things that affect
+  the whole instance
+- Superusers can do anything
+
+To make things more granular and allow some delegation of responsability,
+superusers can grant specific permissions to specific users. Available
+permissions are:
+
+- **Manage instance-level settings**: users with this permission can edit instance
+  settings as described in :ref:`instance-settings`
+- **Manage library**: users with this permission can import new music in the
+  instance
+- **Manage library federation**: users with this permission can ask to federate with
+  other instances, and accept/deny federation requests from other intances
+
+There is no dedicated interface to manage users permissions, but superusers
+can login on the Django's admin at ``/api/admin/`` and grant permissions
+to users at ``/api/admin/users/user/``.