149 lines
7.2 KiB
Markdown
149 lines
7.2 KiB
Markdown
# Settings backup format
|
||
|
||
Backup & restore → Settings exports Calendula's settings to a JSON file and
|
||
imports one back (#481). Events are not part of it; they have the `.ics`
|
||
backup. This file is the schema's source of truth. The envelope and the
|
||
`settings` section come from floret-kit's `core-backup`
|
||
(`BackupFormat`, `PrefsSection`); `data/backup/SettingsBackup*.kt` implements
|
||
the rest.
|
||
|
||
## Top level
|
||
|
||
```json
|
||
{
|
||
"format": "calendula-settings",
|
||
"version": 1,
|
||
"exportedAt": 1700000000000,
|
||
"appVersion": "2.25.0",
|
||
"settings": { … },
|
||
"calendars": [ … ],
|
||
"app": { … }
|
||
}
|
||
```
|
||
|
||
- `format` must be exactly `"calendula-settings"`, or the file is not a
|
||
settings backup.
|
||
- `version` is `1`. A higher version is refused as "from a newer Calendula";
|
||
a change that an older build could misread bumps it.
|
||
- `exportedAt` (epoch ms) and `appVersion` are informational.
|
||
- The file is limited to 8 MiB; a leading byte-order mark is ignored.
|
||
- The `settings` section is required: a file without it would reset every setting.
|
||
|
||
## Parsing rules
|
||
|
||
- **Unknown fields are ignored**, at any level, so a file from a later build
|
||
imports as far as this one understands it.
|
||
- **Known fields are strict.** A known key holding the wrong JSON type rejects
|
||
the whole file before anything is written.
|
||
- **Values are not range-checked.** They are stored as they are and go through
|
||
the same reads every setting already does (clamps, enum fallbacks), so an
|
||
out-of-range or unknown value degrades to the nearest valid one or the
|
||
default.
|
||
|
||
## Import semantics
|
||
|
||
An import **replaces** every setting the backup covers; it does not merge. A
|
||
backed-up setting the file doesn't carry is reset to its default (that is what
|
||
the exporting install had). Everything is written in one DataStore edit. After
|
||
that the import refreshes what reads settings outside DataStore: the
|
||
contact-dates mirror (turned on and synced, or off and torn down, as the
|
||
settings toggle does), the reminder scan, the automatic-backup schedule, the
|
||
launcher name and the app language. Theme and widgets follow the stored
|
||
values on their own. A summary lists what could not be imported.
|
||
|
||
## `settings`
|
||
|
||
The settings stored under their own on-disk key names, in their stored form,
|
||
e.g. `"theme_mode": "DARK"`, `"multi_day_count": 4`,
|
||
`"default_reminder_minutes": "10,60"`. Only keys that have been set are
|
||
written. `SettingsBackupSchema.plain` lists them: appearance, fonts,
|
||
views, the agenda screen, the event form and its default calendar, reminders
|
||
and the daily summary, automatic backup (switch, interval, layout, retention,
|
||
backup on change) and contact special dates (switch, types, title
|
||
templates, year).
|
||
|
||
Three are taken only where this device can honour them, otherwise the current
|
||
value stays and the summary says why:
|
||
|
||
- `brand_font` / `plain_font` set to `custom`: the font file is not in the
|
||
backup, so it is taken only if this install already has one for that role.
|
||
- `special_dates_enabled` on: needs the contacts permission here.
|
||
- `auto_backup_enabled` on: needs a backup folder chosen on this install.
|
||
|
||
## `calendars`
|
||
|
||
Per-calendar settings are stored by provider id, which means nothing on
|
||
another device. Each calendar with any of them is written with a portable
|
||
identity instead:
|
||
|
||
| Field | Type | Notes |
|
||
|---|---|---|
|
||
| `account_name` | String | Required. |
|
||
| `account_type` | String | Required. |
|
||
| `display_name` | String | Required. |
|
||
| `special_dates` | String? | `Birthday`/`Anniversary`/`Custom` for a contact-dates mirror calendar. |
|
||
| `hidden` | Boolean | Hidden in the drawer's filter. |
|
||
| `last_used` | Boolean | Preselected for new events. |
|
||
| `event_duration_minutes` | Int? | Per-calendar default length, clamped to 1–1440 like the setting. |
|
||
| `reminders` | Int[]? | Timed reminder override; `[]` is "no reminder". |
|
||
| `all_day_reminders` | Int[]? | All-day reminder override. |
|
||
| `hidden_in_views` | String[]? | Views it is hidden in only (`Month`, `Week`, …); unknown names are dropped. |
|
||
| `notifications` | Boolean? | `false`: Calendula posts none of its reminders. |
|
||
| `alert_style` | String? | `full_screen` or `full_screen_ring`; absent or unknown is a plain notification. |
|
||
| `fixed_time_reminder` | String? | Set-time reminder override: `off`, or `days@minuteOfDay` (e.g. `1@1200`). Absent or unreadable inherits the default. |
|
||
| `in_daily_digest` | Boolean? | `false`: left out of the daily summary. |
|
||
| `auto_backup` | Boolean? | The automatic backup's choice for it; absent follows the default for its kind. |
|
||
|
||
On import an entry matches the one calendar here with the same account name,
|
||
account type and display name. No match, or more than one, skips it and the
|
||
summary names it, as does a calendar the file itself lists twice under one
|
||
identity. Reminder lists are stored the way the setters store them (no
|
||
negative values, each once, ascending). A mirror calendar matches by `special_dates` instead, since
|
||
its name is localised, and only when the imported settings keep the mirror on
|
||
and the type (otherwise the import tears that calendar down). When the mirror has not created it yet,
|
||
it is matched after the import's sync. Every mirror's all-day reminders are
|
||
applied through the mirror so its existing events follow; one the file doesn't
|
||
override inherits the default again. An id in the prefs whose calendar no
|
||
longer exists is left out of the export.
|
||
|
||
If this device's calendars can't be read, the per-calendar settings here are
|
||
left untouched and the summary says so; an export in that state fails rather
|
||
than writing a file without them.
|
||
|
||
## `app`
|
||
|
||
| Field | Type | Notes |
|
||
|---|---|---|
|
||
| `language` | String? | The app language tag; `null` follows the system. Absent: left as is. A language this build doesn't ship is skipped. |
|
||
| `launcher_name` | String? | `CALENDULA` or `CALENDAR`. Unknown: left as is. |
|
||
|
||
## Not exported
|
||
|
||
`SettingsBackupSchema.excluded`, each for a reason: this install's own state,
|
||
bookkeeping, or meaningless on another device.
|
||
|
||
- Font stamps (`*_font_stamp`): cache keys for the local font file.
|
||
- `agenda_widget_range`, `widget_size`: legacy defaults for unconfigured
|
||
widgets. Widget configuration is not part of the backup at all.
|
||
- `recent_time_zones`, `recent_fixed_time_reminders`: usage history.
|
||
- `notification_category_hint_dismissed`, `reminder_channel_versions`:
|
||
this install's notification hint and channels.
|
||
- `sync_access_dismissed`: sync-request grants of this device's accounts.
|
||
- `daily_digest_armed_at`, `reminder_last_digest_day`: daily summary bookkeeping.
|
||
- `auto_backup_files`, `auto_backup_fingerprints`: what the automatic backup
|
||
wrote to this install's folder.
|
||
- Onboarding progress and `visibility_notice_pending`.
|
||
- `auto_backup_folder_uri`: a SAF grant does not survive a reinstall or
|
||
another device.
|
||
- Run status: `auto_backup_last_*`, `auto_backup_failures`,
|
||
`special_dates_last_run`, `special_dates_stalled_reason`,
|
||
`special_dates_last_foreground_sync`.
|
||
- `special_dates_calendar_*`: the mirror re-adopts its calendars by their
|
||
provider marker.
|
||
- `disabled_calendar_ids`: switch-offs not yet written to this device's
|
||
provider. Whether a calendar is switched on lives in the provider.
|
||
- `reminder_last_scan_millis`: the reminder delivery watermark.
|
||
|
||
`SettingsBackupSchemaTest` fails for any stored key that is in none of the
|
||
three lists, so a new setting has to be placed before it ships.
|