From 88b6640f1fcc07134ff0c747bd8d572ecaf51af2 Mon Sep 17 00:00:00 2001
From: Yacine Rezgui <rezgui.y@gmail.com>
Date: Thu, 13 Jan 2022 14:49:26 +0000
Subject: [PATCH] Add storage permissions usage guide

---
 docs/permissions.md | 31 +++++++++++++++++++++++++++++++
 mkdocs.yml          |  6 +++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/docs/permissions.md b/docs/permissions.md
index fe07b1e6..6641371c 100644
--- a/docs/permissions.md
+++ b/docs/permissions.md
@@ -18,6 +18,35 @@ implementation("com.google.modernstorage:{{ artifact }}:{{ lib_version }}")
 ## API reference
 `{{ artifact }}` API reference is available [here][api_reference].
 
+## Storage Permissions usage
+
+Android provides two types of storage to save files:
+
+* App-specific (internal folder, external app folder)
+* Shared (visible using the system file manager)
+
+With the introduction of Scoped Storage in Android 10 (API 29), the storage access has deeply
+changed:
+
+* You can add media & document files without any permission, reading and editing media files
+created by other apps require `READ_EXTERNAL_STORAGE`
+* Document files created by other apps are readable only using the [Storage Access Framework][saf_guide]
+
+To help you navigate common use cases, check out the below table:
+
+| Actions                                            | API 29-                  | API 29+                     |
+|----------------------------------------------------|--------------------------|-----------------------------|
+| Read media files (created by self)                 | `READ_EXTERNAL_STORAGE`  | No permission needed        |
+| Read media files (created by all apps)             | `READ_EXTERNAL_STORAGE`  | `READ_EXTERNAL_STORAGE`     |
+| Add file (media, document)                         | `WRITE_EXTERNAL_STORAGE` | No permission needed        |
+| Edit & Delete media files (created by self)        | `WRITE_EXTERNAL_STORAGE` | No permission needed        |
+| Edit & Delete media files (created by all apps)    | `WRITE_EXTERNAL_STORAGE` | `READ_EXTERNAL_STORAGE` 1️⃣  |
+| Edit & Delete document files (created by self)     | `WRITE_EXTERNAL_STORAGE` | No permission needed        |
+| Edit & Delete document files (created by all apps) | `WRITE_EXTERNAL_STORAGE` | Storage Access Framework    |
+
+> 1️⃣ When editing or deleting media files created by other apps on API 29+ (Android 10), you have to
+> request explicitly user's consent. Read more [here][edit_media_scoped_storage].
+
 ## Check if app can read files
 
 ```kotlin
@@ -55,3 +84,5 @@ storagePermissions.canReadAndWriteFiles(
 ```
 
 [api_reference]: /modernstorage/api/permissions/
+[saf_guide]: https://developer.android.com/training/data-storage/shared/documents-files
+[edit_media_scoped_storage]: https://developer.android.com/training/data-storage/shared/media#update-other-apps-files
diff --git a/mkdocs.yml b/mkdocs.yml
index 90cacc4b..01f9d36d 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -23,6 +23,7 @@ nav:
 
 # Extensions
 markdown_extensions:
+    - tables
     - admonition
     -   codehilite:
             guess_lang: false
@@ -34,6 +35,9 @@ markdown_extensions:
     - pymdownx.tabbed
     -   pymdownx.tasklist:
             custom_checkbox: true
+    -   pymdownx.emoji:
+            emoji_index: !!python/name:materialx.emoji.twemoji
+            emoji_generator: !!python/name:materialx.emoji.to_svg
 
 # Plugins
 plugins:
@@ -41,4 +45,4 @@ plugins:
     - macros
 
 extra:
-    lib_version: "1.0.0-alpha03"
+    lib_version: "1.0.0-alpha04"