page about preserving settings

Author: caesay

docs/integrating/overview.mdx

@@ -98,6 +98,8 @@ It is recommended that you use one of the functions which explicitly applies a p
 :::
 
 ## How updates work
+
+### On Windows
 In a typical Windows install the application structure will look like this:
 ```
 %LocalAppData%
@@ -111,4 +113,10 @@ In a typical Windows install the application structure will look like this:
 
 `sq.version` is a special file created by Velopack which contains some metadata about your currently installed application. During install/uninstall, the entire `{packId}` folder is replaced or removed. During updates, only the `current` folder is replaced. If you store settings in the same folder as your main binary, they will be erased during updates. 
 
-If you want to create files that persist through updates, but are erased when the app is uninstalled, you should store them one level up (`..`) outside of the `current` dir. If you want to create files which persist even if the app is uninstalled (eg. important user settings) then you should store them in `%AppData%\{packId}` (that's the roaming app data, not local app data).
+:::warning
+Since `current` is replaced with the new version during updates, it's not safe to store settings, logs, etc in the `current` dir where your app lives. See ***[Preserving Files](./preserved-files.mdx)*** for more info.
+:::
+
+### On Linux & Mac
+On these platforms, the app is stored as a single (typically read-only) bundle like `.app` or `.AppImage`. The bundle is replaced during updates in a single atomic operation.
+If you have any files you wish to persist (settings, logs, etc) you must find a directory elsewhere on the filesystem to store these files.

docs/integrating/preserved-files.mdx

@@ -0,0 +1,19 @@
+# Preserving Files & Settings
+<AppliesTo all />
+Your application binary files get completely replaced during updates, so you should not store important files in the same directory as your application binary files.
+
+## Application Settings
+
+If you want to create settings that persist through updates, but are erased when the app is uninstalled, on Windows you should store them one level up (`..\`) outside of the `current` dir. 
+
+If you want to create files which persist even if the app is uninstalled (eg. important user settings) then you should store them in `%AppData%\{packId}` (that's the ***roaming app data***, not local app data where the app lives).
+
+## Sentry / Crashpad / Error Reporting
+Many error crash handling utilities will store error/crash reports to the application directory by default, and will upload them as a report the next time the application starts.
+
+You need to ensure any of these libraries can be configured with a database / storage directory outside of the current application directory somewhere. 
+On Windows, you just need to be outside the `%LocalAppData\{packId}\current` directory. So you could use `..\` (this is the same as `%LocalAppData\{packId}`). 
+
+## Non-Windows
+For other non-Windows operating systems, you should search online to find best practices about where to store settings/log files for installed apps. 
+The recommended location is OS / distro specific, and might be in `/var` or somewhere in user home `~` (eg. `~/Library/Application Support` on MacOS).