About baking up settings.

Settings backups.md

@@ -0,0 +1,31 @@
+# Settings backups
+Heavy users of this plugin may end up defining over 50 shell commands in their settings. It's a ton to remember if it has to be redone due to a hardware failure, corrupted settings file, or other accident. This note will discuss about two ways to to backup - manual and automatic.
+
+## Manual backups are important
+
+The *Shell commands* plugin's settings are stored in a single file: `.obsidian/plugins/obsidian-shellcommands/data.json`. Make sure to include it in your backups every time you back up your vault (you are backing up your vault, are you??). Even if you are doing automatic backups, it's good to check occasionally that the settings file really is included in the backups.
+
+## Automatic backups after SC version upgrades
+Every time the *Shell commands* plugin notices that the `data.json` settings file format is for an older version of SC (e.g. after upgrading the plugin), the plugin will automatically create a backup copy of the file in the same folder, and migrate the actual `data.json` file to comply with a new settings file format needed for new features.
+
+Backup file naming logic:
+- _data-backup-version-**0.x**-before-upgrading-to-**0.7.0**.json_: Here **0.x** means that the original settings file is from SC version 0.0.0 - 0.6.0. It's marked 0.x because before `0.7.0` the settings files do not have version information available. And the later version number, **0.7.0** in this case, tells before which upgrade this backup file was created.
+- _data-backup-version-**0.7.0**-before-upgrading-to-**0.8.0**.json_: This is how the versioning will be in future updates. Here **0.7.0** is the original settings file's version, and **0.8.0** tells before which upgrade this backup was taken.
+- (If a backup file already exists with the same name, a new backup file will have `-2` (or `-3` etc.) added to its name.)
+
+These backups are meant to help you in case the migrating process has a bug that corrupts the settings file, or removes data from it. SC's migrations should never affect other settings in Obsidian or other plugins, but you should naturally backup those, too.
+
+**As these backups happen infrequently, it's recommended that you take regular manual backups, too.**
+
+### Restoring settings from a backup after a problematic SC upgrade
+If an upgrade caused problems to your SC settings, you should first [[downgrade]] the plugin to a previous version that you knew worked correctly, before trying to restore a backup settings file. Otherwise you'll end up running the problematic upgrade migration again.
+
+To restore a backup settings file, do:
+1. Quit Obsidian and [[downgrade]] the plugin.
+2. Go to `.obsidian/plugins/obsidian-shellcommands` folder.
+3. Rename `data.json` settings file to something like `problematic-data.json` or something else.
+4. Pick a backup file that's named like `data-backup-version-x.x.x-before-upgrading-to-y.y.y.json`, and rename it to `data.json`.
+6. Launch Obsidian again and check that everything works.
+
+# History
+[0.7.0 #TODO add date and fix link](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#070): Started making automatic backup of the settings file after upgrades. ([#83](https://github.com/Taitava/obsidian-shellcommands/issues/83)).

Upgrading.md

@@ -1,5 +1,4 @@
 #TODO:
-- data.json backups - the automatic backup + mention that a user should take their own backups.
 - How to downgrade if problems occur.
 
 # Upgrading
@@ -21,4 +20,6 @@ The *Shell commands* plugin uses [Semantic Versioning](https://semver.org) when
 3. If an upgrade is available, you should see an *Update* button next to *Shell commands*:
   ![[Settings-community-plugins-update-shell-commands.png]]
 4. Click the button and Obsidian will do the rest.
-
+
+ ### Automatic backups of settings after an upgrade
+ The *Shell commands* plugin creates a backup file of its setting after each upgrade from version `0.7.0` onward. To learn more, see [[Settings backups#Automatic backups after SC version upgrades]].