Start a guide to sandbox permissions

Apps/Guides/Permissions/_files/example.json

+{
+    "app-id": "com.example.some_example",
+    "runtime": "org.gnome.Platform",
+    "runtime-version": "3.32",
+    "sdk": "org.gnome.Sdk",
+    "command": "my-program",
+    "finish-args": [
+        "--socket=wayland",
+        "--filesystem=~/.config/dconf:ro",
+        "--talk-name=ca.desrt.dconf",
+        "--env=DCONF_USER_CONFIG_DIR=.config/dconf"
+    ],

Apps/Guides/Permissions/index.rst

+Sandbox Permissions
+===================
+
+When applications are distributed as flatpaks they need permission to access
+certain features on the phone. This is done by requesting permissions in the
+Flatpak manifest file. The table below shows which permissions correspond to
+which features.
+
+.. |br| raw:: html
+
+   <br />
+
+======================================= ================================================
+Feature                                 Flatpak Permissions
+======================================= ================================================
+Display a graphical user interface.     ``--socket=wayland``
+Access the Internet using sockets.      ``--share=network``
+Access settings (GNOME applications)    ``--filesystem=~/.config/dconf:ro`` |br|
+                                        ``--talk-name=ca.desrt.dconf`` |br|
+                                        ``--env=DCONF_USER_CONFIG_DIR=.config/dconf``
+======================================= ================================================
+
+Asking for Permission
+---------------------
+
+The permissions required by an application are included in the ``finish-args``
+entry of its manifest. The following example shows the first part of a manifest
+for an application that uses the display and maintains user-specific settings:
+
+.. literalinclude:: _files/example.json
+   :language: json
+
+A more detailed description of permissions is given in the `Flatpak Sandbox
+Permissions`_ section of the Flatpak documentation.
+
+.. include:: /links.txt

Apps/Guides/index.rst

@@ -11,6 +11,7 @@ to encounter. We aim to add more guides to this collection over time.
    :maxdepth: 1
 
    Design/index
+   Permissions/index
    Porting_GNOME_Applications/index
    Simple_Input_Output/index
 

links.txt

@@ -12,6 +12,7 @@
 .. _`Flatpak Building Introduction`: http://docs.flatpak.org/en/latest/building-introduction.html
 .. _`Flatpak debugging documentation`: http://docs.flatpak.org/en/latest/debugging.html
 .. _`Flatpak documentation`: http://docs.flatpak.org/en/latest/
+.. _`Flatpak Sandbox Permissions`: http://docs.flatpak.org/en/latest/sandbox-permissions.html
 .. _`Gio.GApplication documentation`: https://developer.gnome.org/gio/stable/GApplication.html#g-application-id-is-valid
 .. _`git-buildpackage`: http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.html
 .. _`Glade`: https://glade.gnome.org/