~anjan/sxmo-docs-stable

1bebfb96ed83eaca9dcbd2ff61ebc25296f20e64 — Maarten van Gompel 2 years ago 5a8eda5
wrote section about reworked migrations
1 files changed, 33 insertions(+), 8 deletions(-)

M USERGUIDE.md
M USERGUIDE.md => USERGUIDE.md +33 -8
@@ 278,8 278,8 @@ calls/texts. If your SIM is locked, you must unlock it manually.  The scripting 
If you have issues with delayed or not receiving smses, you can follow this to
debug:

Modemmanager can get stuck/miss certain texts if they have unexpected content. 
To check if this is the case, make sure `sxmo_modemmonitor.sh` is running to monitor 
Modemmanager can get stuck/miss certain texts if they have unexpected content.
To check if this is the case, make sure `sxmo_modemmonitor.sh` is running to monitor
for new texts and run: `mmcli -m any --messaging-list-sms`.
If some sms are listed, that means modemmonitor is stuck. You can view the
content of these sms via mmcli once and they will be removed forever.


@@ 838,12 838,37 @@ or in ``~/.config/sxmo/profile`` if they are sxmo specific.

### **Update migrations**

While developing Sxmo, we will eventually update the xinit/sway template, or
environment variable names, or update hooks or whatever. We use a script
named `sxmo_migrate.sh` that try to simplify migrations. This script will
first show the differences between configurations can also override them
completely. You should run this script after every Sxmo to check if your hooks/configs
are up to date enough with the latest version of the system.
While developing Sxmo, we will regularly update certain configuration files such as the xinit/sway template, the
hooks or whatever. These files are typically a mixture of changes by us, and customizations by the user. This mixture
gives the user maximum flexibility to adapt Sxmo to his/her liking. This does imply that, when we update
such files, the challenge is to ensure that user modifications can be easily merged back in again, and that the system
is never in a broken state because of outdated configurations and version mismatches.

Whenever your configuration files are out-of-date when starting Sxmo, they will be moved aside (i.e. renamed with
``.needs-revision`` extension) and the default configuration will take its place. A red notification will pop up telling you
have configuration files that need to be migrated. This migration is done
by running a script named `sxmo_migrate.sh`. This script can simply be launched from the configuration menu.
It first shows the differences between your configuration and the new default, and allows you to edit and apply your
configuration accordingly.

*Techical details*:

Sxmo (since 1.8.1) uses versioned configuration files, meaning that they each carry a simple version number unique to
the file, this version number is expressed in a comment in the file itself, such as:

```
# configversion: 1
```

You should **only** update this version number when ``sxmo_migrate.sh`` prompts you to do so by showing a diff with a newer
configversion number.

If you want to see what files are disabled and need migration, run ``sxmo_migrate.sh state``. If you want to revert
**all** your configuration files to the default, then you can run ``sxmo_migrate.sh reset``. This is usually a last
resort if you end up with a broken system and can be considered a kind of factory reset.

The process that checks the versions of your configuration files is ``sxmo_migrate.sh sync``, it runs automatically when
Sxmo starts.

### **X resources**