Update docs

docs/README.MD

@@ -1,7 +1,7 @@
 # Magisk Documentations
-(Updated on 2017.8.16) ([Changelog](changelog.md))
+(Updated on 2017.9.28) ([Changelog](changelog.md))
 
-## Table of Content
+## Table of Contents
 
 - [Introduction](#introduction)
 - [Procedure Diagram](https://cdn.rawgit.com/topjohnwu/Magisk/cc1809688299f1f8b5db494a234850852712c0c9/docs/procedures.html)
@@ -19,6 +19,7 @@
     - [Modules and Templates](module_repo.md#magisk-module-format)
     - [Submit Modules to Repo](module_repo.md#submit-your-module-to-magisk-modules-repo)
 - [Tips and Tricks](tips.md)
+    - [OTA Installation Tips](tips.md#ota-installation-tips)
     - [Remove Files](tips.md#remove-files)
     - [Remove Folders](tips.md#remove-folders)
 

docs/applets.md

@@ -8,32 +8,27 @@ Command help message:
 
 ```
 Usage: magisk [applet [arguments]...]
-   or: magisk --install [SOURCE] DIR
-       if SOURCE not provided, will link itself
-   or: magisk --list
-   or: magisk --createimg IMG SIZE
-       create ext4 image, SIZE is interpreted in MB
-   or: magisk --imgsize IMG
-   or: magisk --resizeimg IMG SIZE
-       SIZE is interpreted in MB
-   or: magisk --mountimg IMG PATH
-       mount IMG to PATH and prints the loop device
-   or: magisk --umountimg PATH LOOP
-   or: magisk --[boot stage]
-       start boot stage service
-   or: magisk [options]
-   or: applet [arguments]...
+   or: magisk [options]...
+
+Options:
+   -c                        print current binary version
+   -v                        print running daemon version
+   -V                        print running daemon version code
+   --list                    list all availible applets
+   --install [SOURCE] DIR    symlink all applets to DIR. SOURCE is optional
+   --createimg IMG SIZE      create ext4 image. SIZE is interpreted in MB
+   --imgsize IMG             report ext4 image used/total size
+   --resizeimg IMG SIZE      resize ext4 image. SIZE is interpreted in MB
+   --mountimg IMG PATH       mount IMG to PATH and prints the loop device
+   --umountimg PATH LOOP     unmount PATH and delete LOOP device
+   --[boot stage]            start boot stage service
+   --unlock-blocks           set BLKROSET flag to OFF for all block devices
 
 Supported boot stages:
    post-fs, post-fs-data, service
 
-Options:
-   -c          print client version
-   -v          print daemon version
-   -V          print daemon version code
-
 Supported applets:
-    su, resetprop, magiskpolicy, supolicy, sepolicy-inject, magiskhide
+    su, resetprop, magiskpolicy, supolicy, magiskhide
 ```
 
 ### su
@@ -86,7 +81,7 @@ resetprop  --delete NAME     remove prop entry NAME
 ```
 
 ### magiskpolicy
-(This tool is aliased to `supolicy` and `sepolicy-injection` for legacy reasons)
+(This tool is aliased to `supolicy` for compatibility)
 
 A tool to patch `sepolicy`. **magiskpolicy** also comes with built-in rules to unleash restrictions to make Magisk work properly. `sepolicy` is a compiled binary containing SELinux rules; we directly patch rules in the binary format since we don't have access to the SELinux policy source (`*.te`) files.
 

docs/changelog.md

@@ -1,3 +1,6 @@
 # Changelog
 - 2017.8.16
-    - Initial version for Magisk v13.5+
+    - Initial version for Magisk v13.5
+- 2017.9.28
+    - Update applets info to Magisk v14.1
+    - Add OTA tips

docs/module_repo.md

@@ -61,7 +61,7 @@ If you want to share your module with others, you can submit your modules to [Ma
 
 #### Once your module is live on the Modules Repo, the description of your repo should be the ID of your module. Please do NOT change the description, repeat, do NOT change the description.
 
-![repo_description.png](repo_description.png)
+![repo_description.png](images/repo_description.png)
 
 ## Notes
 - The Module Template depends on external scripts, be aware of the minimal required Magisk version of the template.

docs/tips.md

@@ -1,6 +1,53 @@
 # Tips and Tricks
+
+## OTA Installation Tips
+Magisk do modifications systemless-ly, which means applying official OTAs is much simpler. Here I provide a few tutorials for several different kind of devices to apply OTAs and preserve Magisk after the installation if possible.
+
+**This tutorial is only for Magisk v14.1+**
+
+**NOTE: In order to apply OTAs, you HAVE to make sure you haven't modified `/system` (and `/vendor` if available) in anyway, even remounting the partition to rw will tamper block verification!!**
+
+#### Prerequisites
+1. Please disable *Automatic system updates* in developer options, so it won't install OTAs without your acknowledgement.  
+    <img src="images/disable_auto_ota.png" width="250">
+1. When an OTA is available, please go to Magisk Manager → Uninstall → Restore Stock Boot. **Do not reboot immediately or you will have Magisk uninstalled.** This will restore your boot back to 100% untouched stock boot image in order to pass boot verification. **This step is required before doing any of the following steps written below!**  
+    <img src="images/restore_boot.png" width="250">
+
+#### Devices with A/B Partitions
+(Includes Pixel family)
+
+Due to the fact that these devices have two separate partitions and the OTA installation happens live when the system is still running, these devices have the best support: the out-of-the-box OTA installation works seamlessly and Magisk will be preserved after the installation.
+
+1. After restoring stock boot image, apply OTAs as you normally would (Settings → System → System Updates)
+1. Once the installation passed step 1 and starting step 2, go to Magisk Manager → Install → Install to Second Slot. This will install Magisk into the second boot image slot, which is the updated slot.  
+    <img src="images/ota_step2.png" width="250"> <img src="images/install_second_slot.png" width="250">
+1. Let the OTA finish its job. After a reboot, the bootloader will switch to the updated system. Magisk should still be installed since we already patched the new boot image.
+
+#### Devices with FlashFire Support
+(Includes Pixel family, Nexus family, Samsung devices)  
+(If you are using a device with A/B partitions, I **strongly** recommend you to use the method stated above since it uses the stock OTA installation mechanism and will always work under any circumstances)
+
+The [FlashFire](https://play.google.com/store/apps/details?id=eu.chainfire.flash) app developed by Chainfire is a great app to apply OTAs and preserve root at the same time. However, whether it supports your device/system combination depends on the application itself, and support may also change in the future. If you face any issues, please directly [report to Chainfire](https://forum.xda-developers.com/general/paid-software/flashfire-t3075433).  
+
+1. After restoring the stock boot image, download the OTA (Settings → System → System Updates), **do not press reboot to install.**
+1. Open FlashFire, it should detect your OTA zip. Select OK in the popup dialog to let it do its setup.
+1. Please use the options shown in the screenshot below. The key point is to disable EverRoot (or it will install SuperSU), and add a new action to flash Magisk zip **after** the OTA update.zip (the update.zip is auto generated in the previous step).  
+    <img src="images/flashfire.png" width="250">
+1. Press the big **Flash** button, after a few minutes it should reboot updated with Magisk installed.
+
+#### Other Devices - General Case
+Unfortunately, there are no real good ways to apply OTAs on all devices. Also, the tutorial provided below will not preserve Magisk - you will have to manually re-root your device after the upgrade, and this will require PC access. Here I share my personal experience with my daily driver - HTC U11.
+
+1. To properly install OTAs, you should have your stock recovery installed on your device. If you have custom recovery installed, you can restore it from your previous backup, or dumps found online, or factory images provided by OEMs.  
+If you decide to start by installing Magisk without touching your recovery partition, you have a few choices, either way you will end up with a Magisk rooted device, but recovery remain stock untouched:
+    - If supported, use `fastboot boot <recovery_img>` to boot the custom recovery and install Magisk. 
+    - If you have a copy of your stock boot image dump, install Magisk by patching boot image via Magisk Manager, and manually flash it through download mode / fastboot mode / Odin
+1. Once your device have stock recovery and stock boot image restored, download the OTA. Optionally, once you downloaded the OTA update zip, you can find a way to copy the zip out since you are still rooted. Personally I will extract the stock boot image and recovery image from the OTA zip for future usage (to patch via Magisk Manager or restore stock recovery etc.)
+1. Apply and reboot your device. This will use the official stock OTA installation mechanism of your device to upgrade your system.
+1. Once it's done you will be left with an upgraded, 100% stock, un-rooted device. You will have to manually flash Magisk back. Consider using the methods stated in step 1. to flash Magisk without touching the recovery partition if you want to receive stock OTAs frequently.
+
 ## Remove Files
-How to efficiently remove a file systemless-ly? To actually make the file **disappear** within the folder is complicated (possible, not worth the effort). **Replacing it with a dummy file should be good enough**! Create an empty file with the same name and place it in the same path within a module, then you're basically done!
+How to efficiently remove a file systemless-ly? To actually make the file **disappear** is complicated (possible, not worth the effort). **Replacing it with a dummy file should be good enough**! Create an empty file with the same name and place it in the same path within a module, it shall replace your target file with a dummy file.
 
 ## Remove Folders
-Same as mentioned above, actually making the folder to **disappear** is not worth the effort. **Replacing it with an empty folder should be good enough**! A handy trick for module developers using [Magisk Module Template](https://github.com/topjohnwu/magisk-module-template) is to add the folder you want to remove into the `REPLACE` list within `config.sh`. If your module doesn't provide a correspond folder, it will create an empty folder, and automatically add `.replace` into the empty folder so the dummy folder will properly replace the one in `/system`.
+Same as mentioned above, actually making the folder to **disappear** is not worth the effort. **Replacing it with an empty folder should be good enough**! A handy trick for module developers using [Magisk Module Template](https://github.com/topjohnwu/magisk-module-template) is to add the folder you want to remove into the `REPLACE` list within `config.sh`. If your module doesn't provide a correspond folder, it will create an empty folder, and automatically add `.replace` into the empty folder so the dummy folder will properly replace the one in `/system`.