Configuration migration

By default, Desomnia converts older settings each time it loads a configuration, without modifying the file on disk. Persistent migration saves the converted configuration to the source file.

Persistent migration

Add the following processing instruction after the XML declaration and before the outermost element. Leave the existing format version unchanged for this first run:

<?xml version="1.0" encoding="utf-8"?>
<?config autoMigrate="transient|persistent" writeBackupXML="monitor.v?.xml"?>
<SystemMonitor version="1" timeout="5min" onDemand="sleepless" onIdle="sleep">
  <PowerRequestMonitor />
</SystemMonitor>

When this example is loaded, Desomnia applies all automatic migrations to the latest format version, and saves the file. Before replacing it, Desomnia copies the original to monitor.v1.xml beside it. A comment in the updated file records the conversion.

If a migration produces a warning, this policy continues with the converted settings in memory but does not save the affected step. Review the log and resolve migration warnings before considering the saved file fully converted.

Configuration

The optional <?config ...?> instruction belongs before <SystemMonitor> or <EnvironmentMonitor>, and before any <?system ...?> instructions. Use it only once.

autoMigrate

default:: transient

Controls whether older settings are converted and whether the result is saved:

transient: Converts settings in memory and leaves the source file unchanged. Migration messages recur on subsequent starts or reloads until the file is updated.
transient|persistent: Saves migration steps that complete without warnings. Continues in memory if a step needs review or the file cannot be written.
persistent: Saves each migration step that completes without warnings. Stops if a step needs review or cannot be written, ensuring that the running configuration matches the saved file.
never: Disables conversion. A configuration too old for the installation is rejected. none is an alias; neither value can be combined with another policy.

writeBackupXML

The backup path for the original configuration before a persistent migration. The service account requires write access to both the configuration and backup. The backup path must differ from the source path.

Relative paths are resolved beside the configuration file. A ? in the name is replaced by the old format version. Without ?, a later backup replaces the earlier backup at that path.

version

An alternative to the version attribute on the outermost element, for example <?config version="3"?>. If both locations declare a version, the numbers must agree. See Versioning.

Migration messages

Each migration message identifies the affected element or attribute:

INFO: an automatic change, such as renaming an option.
WARN: review the change before saving it. The initial announcement that migration is starting is also logged at this level.
ERROR: the conversion cannot be completed; fix the configuration before starting Desomnia again.

Migration handles known old settings, not every possible typo or custom configuration. Unknown options may be ignored, so compare custom settings with the current module reference if they appear to have no effect.

Output format

The format version is updated, and existing comments and layout are largely preserved. Attribute formatting can change when an element is rewritten. A backup is therefore useful even when all changes are automatic.

See Format history for the changes made by each format version and Troubleshooting if a configuration fails to load.