Upgrade Guide

Upgrade Guide

This page describes the dev documentation baseline: configuration schema 5 and GTK 4.18 or newer. Use it when moving an existing UnixNotis installation or preset forward from the 1.2-era wiki.

Before changing the installation

Record the current state first:

cp -a "${XDG_CONFIG_HOME:-$HOME/.config}/unixnotis"   "${XDG_CONFIG_HOME:-$HOME/.config}/unixnotis.before-upgrade"

If the old CLI provides diagnostic commands, run those using the old documentation. Do not assume that target CLI commands exist until the new binaries have been installed.

For every preset you distribute, inspect it before importing or re-exporting:

noticenterctl preset inspect setup.unixnotis
noticenterctl preset import setup.unixnotis --dry-run

Do not delete old theme directories until the active [theme] paths have been checked.

Compatibility baseline

Area	Development baseline
Configuration	config_version = 5
GTK	GTK 4.18 or newer
Display server	Wayland
Theme layers	base.css, panel.css, popup.css, widgets.css, media.css
Default service manager	systemd --user
Other service backends	dinit, runit, s6
Private control API	versioned; query GetApiVersion()

The installer checks GTK before writing binaries, configuration, or service files. Removing that check does not make GTK 4.17 or older compatible with the current CSS and popup APIs.

Update the binaries

For a release archive, keep the installer, manifest, and bin/ directory together and run:

./unixnotis-installer

From a source checkout:

cargo run --release -p unixnotis-installer

After installation, validate the selected user service and use the new CLI:

systemctl --user status unixnotis-daemon.service
# or the matching dinit, runit, or s6 status command

noticenterctl doctor --verbose
noticenterctl css-check
noticenterctl list-active --full
noticenterctl refresh-applications

If the compositor session environment changed, synchronize it explicitly:

noticenterctl sync-session-environment

The environment command belongs to the new CLI. Do not use it as a pre-upgrade step unless the old installation already provides it.

When changing service managers, install with the explicit backend and then synchronize the session:

unixnotis-installer --service-manager dinit
noticenterctl sync-session-environment --service-manager dinit
noticenterctl doctor --verbose --service-manager dinit

See Service Managers and Session Environment for the equivalent systemd, runit, and s6 commands and the environment-file locations.

Move the configuration to schema 5

Set the schema marker at the document root:

config_version = 5

Unversioned files and files declaring any older or newer schema are rejected. There is no silent schema migration. A partial file that wants current defaults must declare version 5 and then receives defaults for omitted fields. Preserve the old file before editing it so fields with changed meaning can be reviewed rather than guessed.

Review these additions:

[panel]
no_matching_text = "NO MATCHING NOTIFICATIONS"
notification_thumbnails_visible = false
notification_avatars_visible = true

[media]
local_art_policy = "all_admitted"
local_art_executable_allowlist = []

notification_avatars_visible controls daemon-validated conversation images independently from content or decorative thumbnails.

Configuration files larger than 1 MiB are rejected. A failed reload keeps the last valid configuration active.

Understand the timeout contract

The popup banner and active notification are separate clocks. A positive sender timeout closes a non-critical active record even when it is resident; a critical popup can hide while its active record remains.

Input	Result
expire_timeout = 0	no automatic banner hide and no automatic active close
positive timeout, non-critical, resident or not	banner hides and active record closes at the same deadline
positive timeout, critical	banner hides; active record remains
expire_timeout = -1, ordinary	configured banner timeout; active record remains
expire_timeout = -1, non-critical transient, resident or not	configured banner timeout and active close when the timeout is positive
expire_timeout = -1, critical with a configured timeout	popup hides; active record remains
expire_timeout = -1, critical without a configured timeout	popup remains; active record remains

This distinction matters for actions. A positive timeout invalidates non-critical controls when the deadline expires, including for resident rows. Critical active records remain available after their popup hides. Under the default -1 policy, an ordinary row can remain actionable after its banner disappears.

See Notification Lifecycle for replacements, history, replies, DND, and popup reconnect behavior.

Update theme assumptions

Runtime CSS comes directly from the five configured [theme] paths. A local theme.toml is compatibility metadata for theme-directory workflows; normal preset export does not require it and it does not activate a local theme.

Runtime behavior after the upgrade:

• GTK 4.18 custom properties and supported var(...) and calc(...) expressions are valid
• missing or unsafe layers fall back independently to embedded CSS
• existing regular files are preserved during install and repair
• missing external stylesheets are not created
• symlinks and non-regular files are refused
• CSS changes hot-reload, but Rust widget hierarchy changes require a process restart
• the installed unixnotis-svg-renderer helper handles bounded local SVG rasterization

Validate the active files:

noticenterctl css-check

Create a fresh editable copy of the bundled theme without changing active paths:

noticenterctl theme export-stock

See Theming and Security for file boundaries, asset handling, and stable CSS hooks.

Remove stale stock artifacts

Older installations may contain unixnotis-stock, stock-theme, or stock-theme-v2 directories. They are ordinary exported files, not runtime modes. Check the active [theme] paths and run noticenterctl css-check before removing them. Keep any directory still referenced by a configured stylesheet or preset.

Reset and restore safely

The installer and CLI use the same transactional reset operation.

Interactive:

noticenterctl preset reset-config

Unattended:

noticenterctl preset reset-config --yes

Reset creates a backup and atomically replaces the fixed stock targets:

• config.toml
• base.css, panel.css, popup.css, widgets.css, and media.css
• scripts/unixnotis-blue-light-lib
• scripts/unixnotis-blue-light-state
• scripts/unixnotis-blue-light-on
• scripts/unixnotis-blue-light-off

The reset uses the fresh default config paths, so CSS at custom [theme] paths is not reset. Files outside those fixed targets, including theme.toml, exported theme directories, and custom assets, are not deleted.

Restore is performed from the installer UI. It restores files present in the selected snapshot. Script targets are validated, contents are restored atomically, and executable mode 0755 is reapplied. Unsafe or missing entries are skipped with warnings while other eligible files continue restoring.

Re-export presets

Old bundles can contain stale schema defaults, CSS paths, scripts, or asset references. After the new CLI is installed, re-export from the upgraded live setup:

noticenterctl preset inspect old.unixnotis
noticenterctl preset import old.unixnotis --dry-run
noticenterctl preset export current.unixnotis --force

Review any command execution, external CSS, and asset dependency prompts before importing. Do not edit the archive stream by hand.

Inline reply is a KDE-compatible extension. A sender that does not advertise the supported reply action continues to work normally; the extension is not required by the base Freedesktop interface.

Review notification visuals and media art

Conversation avatars, decorative sender visuals, and content images are distinct roles. The daemon decodes and bounds sender visuals before UI transport; clients do not read sender paths.

Media behavior also changed:

• browser players are deduplicated by process identity before metadata fallback
• native local artwork is admitted according to local_art_policy
• browser local-file artwork remains denied
• remote artwork remains HTTPS-only and policy-controlled

Use Widgets, Performance, and Theming and Security for the detailed policy.

Validate the upgraded setup

After the new CLI is installed, run the checks against the exact configuration that will be used:

noticenterctl doctor --verbose
noticenterctl css-check
noticenterctl refresh-applications
noticenterctl explain-notification <ID>

Then verify:

• panel open, close, search, and clear actions
• popup display and expiration for 0, positive, and default timeouts
• DND, including --for and --until
• inline actions and replies on the current generation
• CSS hot reload for all five layers
• reset followed by installer restore
• restored helper-script contents and mode 0755
• media cards with native and browser players
• imported presets with a dry run before commit

If a check fails, keep the backup and use Troubleshooting before removing the old configuration or theme directories.