Ordfoss

SettingsMigration.h header

#include <ew/app/SettingsMigration.h>

Namespace ew::app

SettingsMigrationResult struct

struct ew::app::SettingsMigrationResult

What a one-time settings migration did. Returned rather than logged so a caller can report it and a test can assert on it directly, instead of inferring the outcome from side effects.

Members

bool ew::app::settings::SettingsMigrationResult::alreadyMigrated = false

True when the marker was already present, so this call examined nothing. Distinguishes "already done" from "nothing to do", which look identical in the copy counts.

int ew::app::settings::SettingsMigrationResult::keysCopied = 0

How many keys were written into the destination store.

int ew::app::settings::SettingsMigrationResult::keysSkipped = 0

How many keys the destination already had a value for and were therefore left alone.

bool operator==(const SettingsMigrationResult &, const SettingsMigrationResult &)=default

Two results are equal when every field matches.

Functions

SettingsMigrationResult ew::app::settings::migrateLegacySettings(QSettings &legacy, QSettings &current)

Copies every setting from legacy into current, once, and marks it done.

Renaming the application changes the QSettings identity, and with it the location of the per-user store – on Windows, HKCU\Software\<org>\<application>. Everything the user has configured lives under the old name and becomes unreachable the moment the new name ships: window geometry, dock perspectives, the recent-projects list, theme, interface language, and their AI endpoint and API key. That last pair is the reason this is not a convenience – a key the user pasted in months ago and no longer has a copy of is gone.

Behaviour:

  • If current already carries the marker key, return immediately having touched nothing. The migration must not run twice, or it would overwrite choices the user made after upgrading.
  • Otherwise copy every key legacy holds, recursively through all groups, as a raw QVariant so types survive – dock layout is a QByteArray and the recent-projects list is a QStringList, and a string-only copy would corrupt both.
  • A key the destination already holds is skipped, not overwritten. This only arises when a renamed build ran before this migration shipped; in that case the user's newer choice is the more recent statement of intent and wins.
  • The old keys are never deleted. Leaving them costs nothing and means a user who downgrades to a pre-rename build still finds their settings intact.

Enumerates rather than copying a hand-written list of keys, because settings are added continuously and any such list is wrong by the next release.

Takes both stores by reference so tests can drive it with INI-backed instances instead of the per-user native store, which no test may touch.

QString ew::app::settings::settingsMigrationMarkerKey()

The key written into the destination store to record that the migration has run.

Public because "exactly once" is part of the contract, and a test that cannot see the marker can only demonstrate that indirectly.