Unify Omarchy migrations
This commit is contained in:
Ryan Hughes
+40
-104
@@ -10,13 +10,12 @@ bypass it:
|
||||
|
||||
The design goal is:
|
||||
|
||||
- System/root migrations should run automatically from package transactions when
|
||||
safe.
|
||||
- User/session migrations should never run invisibly from pacman because they may
|
||||
need `$HOME`, DBus/session state, a graphical session, or user interaction.
|
||||
- Users who bypass `omarchy update` should still get system migrations from
|
||||
pacman and should be notified only when their own user migration state is
|
||||
missing a shipped user migration.
|
||||
- `omarchy update` owns the visible update pipeline: package transaction,
|
||||
migrations, post-update hooks, update-state refresh, and restart checks.
|
||||
- Migrations run per-user after pacman finishes, because they may need `$HOME`,
|
||||
DBus/session state, a graphical session, sudo, or user interaction.
|
||||
- Users who bypass `omarchy update` are nudged back by the pacman guard; if they
|
||||
explicitly bypass it, their session is notified when migrations are pending.
|
||||
|
||||
## State and coordination files
|
||||
|
||||
@@ -26,8 +25,7 @@ The design goal is:
|
||||
| `/tmp/omarchy-update.log` | user | Transcript of `omarchy update`, used by `omarchy-update-analyze-logs`. |
|
||||
| `~/.local/state/omarchy/updates/` | user | Update-check state for the shell widget (`packages`, `aur`, `available`, `checked-at`, `error`). |
|
||||
| `~/.local/state/omarchy/current/` | user | Generated active theme, selected theme name, and current background symlink. |
|
||||
| `/var/lib/omarchy/migrations/system/` | root | System migration markers. |
|
||||
| `~/.local/state/omarchy/migrations/user/` | user | User migration markers. |
|
||||
| `~/.local/state/omarchy/migrations/` | user | Per-user migration markers. |
|
||||
| `~/.local/state/omarchy/reboot-required` | user | Optional reboot marker checked by `omarchy-update-restart`. |
|
||||
| `~/.local/state/omarchy/restart-*-required` | user | Optional service/app restart markers checked by `omarchy-update-restart`. |
|
||||
|
||||
@@ -36,83 +34,32 @@ The design goal is:
|
||||
See [`migrations.md`](migrations.md) for the full migration model, authoring
|
||||
guidelines, and troubleshooting notes.
|
||||
|
||||
Migrations are scoped by directory:
|
||||
Migrations live in:
|
||||
|
||||
```text
|
||||
migrations/system/*.sh
|
||||
migrations/user/*.sh
|
||||
migrations/*.sh
|
||||
```
|
||||
|
||||
### System migrations
|
||||
|
||||
System migrations are root-owned, noninteractive fixes for existing installs.
|
||||
They may touch `/etc`, `/usr`, `/boot`, system services, hardware configuration,
|
||||
and other machine-wide state.
|
||||
|
||||
Runner:
|
||||
|
||||
```bash
|
||||
omarchy-migrate-system
|
||||
```
|
||||
|
||||
Completion state:
|
||||
|
||||
```text
|
||||
/var/lib/omarchy/migrations/system/<migration filename>
|
||||
```
|
||||
|
||||
Pacman integration:
|
||||
|
||||
```text
|
||||
pkgbuilds/omarchy/omarchy.install post_upgrade()
|
||||
```
|
||||
|
||||
The `omarchy` package calls `omarchy-migrate-system` from `post_upgrade()`.
|
||||
The runner is idempotent, so repeated calls only check the state files.
|
||||
|
||||
### User migrations
|
||||
|
||||
User migrations are current-user/session fixes. They may touch `~/.config`,
|
||||
`~/.local`, user systemd units, browser/editor preferences, DBus/session state,
|
||||
or ask questions.
|
||||
|
||||
Runner:
|
||||
|
||||
```bash
|
||||
omarchy-migrate-user
|
||||
```
|
||||
|
||||
Public command:
|
||||
They run as the current user through:
|
||||
|
||||
```bash
|
||||
omarchy-migrate
|
||||
```
|
||||
|
||||
Completion state:
|
||||
Completion state is per-user:
|
||||
|
||||
```text
|
||||
~/.local/state/omarchy/migrations/user/<migration filename>
|
||||
~/.local/state/omarchy/migrations/<migration filename>
|
||||
```
|
||||
|
||||
A user migration is pending only when a script exists in `migrations/user/` and
|
||||
that user's matching state file is missing. There is no global root-owned queue
|
||||
for user migrations.
|
||||
Every user gets a chance to run every migration. Migrations run as the user;
|
||||
privileged work should invoke the appropriate helper or privilege prompt.
|
||||
Migrations must be idempotent; if one user already applied a machine-wide repair,
|
||||
the migration should no-op for other users.
|
||||
|
||||
`omarchy-migrate` is the public command. It waits for any active pacman
|
||||
transaction to finish, runs pending system migrations, then runs pending user
|
||||
migrations. It does not need `--force`; migrations should happen when they are
|
||||
pending.
|
||||
|
||||
For watchers and diagnostics, `omarchy-migrate --pending [all|system|user]`
|
||||
prints pending migration names and exits `0` when any are pending. Output is
|
||||
scope-prefixed, for example:
|
||||
|
||||
```text
|
||||
system/100-system.sh
|
||||
user/200-user.sh
|
||||
```
|
||||
|
||||
When no matching migrations are pending, it prints nothing and exits non-zero.
|
||||
For watchers and diagnostics, `omarchy-migrate --pending` prints pending
|
||||
migration names and exits `0` when any are pending. When no migrations are
|
||||
pending, it prints nothing and exits non-zero.
|
||||
|
||||
## Raw pacman guard
|
||||
|
||||
@@ -187,10 +134,8 @@ omarchy-update
|
||||
|
||||
Important behavior:
|
||||
|
||||
- `omarchy update` checks/runs system and user migrations in the same visible
|
||||
terminal via `omarchy-migrate`.
|
||||
- `omarchy update` still benefits from pacman-triggered system migrations
|
||||
because the system migration hook runs as part of the pacman transaction.
|
||||
- `omarchy update` checks/runs migrations in the same visible terminal via
|
||||
`omarchy-migrate` after pacman finishes.
|
||||
- A failure should leave enough output in `/tmp/omarchy-update.log` and the
|
||||
terminal transcript to debug.
|
||||
|
||||
@@ -202,10 +147,9 @@ High-level flow:
|
||||
sudo pacman -Syu
|
||||
├─ pre-transaction guard aborts and tells the user to run omarchy update
|
||||
└─ if explicitly bypassed, upgrades omarchy and related packages
|
||||
├─ omarchy post_upgrade runs omarchy-migrate-system as root
|
||||
└─ user session notices migration directory changes
|
||||
├─ omarchy-update-user-notify.path triggers, if enabled
|
||||
├─ omarchy-migrate-notify checks omarchy-migrate --pending user
|
||||
├─ omarchy-migrate-notify checks omarchy-migrate --pending
|
||||
├─ if this user has missing migration state, show notification
|
||||
└─ click opens terminal: omarchy-migrate
|
||||
```
|
||||
@@ -215,12 +159,11 @@ Fallbacks:
|
||||
- `omarchy-first-run` enables the user notification path unit.
|
||||
- `omarchy-first-run` also invokes `omarchy-migrate-notify` on graphical
|
||||
startup, so users who updated before the path unit existed still get prompted
|
||||
if they have missing user migration state.
|
||||
- The notifier is only a prompt. It does not run user migrations in the
|
||||
background.
|
||||
if they have missing migration state.
|
||||
- The notifier is only a prompt. It does not run migrations in the background.
|
||||
- Direct pacman updates do not run `omarchy-hook post-update` unless the user
|
||||
explicitly runs that hook; without a package-update marker, the only user-side
|
||||
pending state we can derive is missing user migration markers.
|
||||
explicitly runs that hook; without a package-update marker, the only pending
|
||||
state we can derive is missing per-user migration markers.
|
||||
|
||||
## Shell update indicator
|
||||
|
||||
@@ -265,11 +208,9 @@ scripts.
|
||||
| `omarchy-update-confirm` | Gum confirmation copy for `omarchy update`. | **Question.** Could be inlined into `omarchy-update`; separate file only helps keep copy isolated. |
|
||||
| `omarchy-update-keyring` | Ensures Omarchy keyring and Arch keyring are current before the main transaction. | **Keep, but review.** It uses targeted `pacman -Sy` for keyring bootstrapping; acceptable for this special case but should remain tightly scoped. |
|
||||
| `omarchy-update-system-pkgs` | Runs `sudo env OMARCHY_UPDATE_PACMAN=1 pacman -Syu --noconfirm` with targeted transition `--overwrite` entries so the ALPM guard allows the transaction and early package-layout conflicts are handled. | **Keep for now.** Small leaf command, clear/testable. |
|
||||
| `omarchy-migrate-system` | Runs root/system migrations from `migrations/system`. Called by `omarchy` package `post_upgrade()` and by `omarchy-migrate` when system migration state is missing. | **Keep.** This is the important direct-`pacman -Syu` integration. |
|
||||
| `omarchy-migrate-user` | Checks `migrations/user` against this user's state and runs only missing user migrations. Supports `--pending` and prints pending filenames. | **Keep internal.** Public users should generally run `omarchy-migrate`. |
|
||||
| `omarchy-migrate` | Public migration command. Waits for pacman, then runs pending system and user migrations. Supports `--pending [all|system|user]` and prints scope-prefixed pending filenames. | **Keep.** This replaces the discarded `omarchy-update-user-finalize` name and no longer needs `--force`. |
|
||||
| `omarchy-migrate` | Public migration command. Waits for pacman, then runs all pending migrations for the current user. Supports `--pending`. | **Keep.** This replaces the discarded `omarchy-update-user-finalize` name and no longer needs `--force`. |
|
||||
| `omarchy-update-pacman-guard` | ALPM pre-transaction guard that aborts direct `pacman -Syu` style upgrades unless Omarchy set `OMARCHY_UPDATE_PACMAN=1` or the user explicitly set `OMARCHY_ALLOW_DIRECT_PACMAN=1`. | **Keep internal/hidden.** This is what nudges users back to `omarchy update`. |
|
||||
| `omarchy-migrate-notify` | Internal notification helper for direct pacman updates. Uses `omarchy-migrate --pending user` and shows notification only when this user has pending migrations. | **Keep internal/hidden.** Clear name now that the public command is `omarchy-migrate`. |
|
||||
| `omarchy-migrate-notify` | Internal notification helper for direct pacman updates. Uses `omarchy-migrate --pending` and shows notification only when this user has pending migrations. | **Keep internal/hidden.** Clear name now that the public command is `omarchy-migrate`. |
|
||||
| `omarchy-update-user-notify` | Hidden compatibility wrapper for `omarchy-migrate-notify`. | **Temporary.** Keep only for old callers. |
|
||||
| `omarchy-update-available` | Update checker for shell widget and post-update refresh. Writes update state. | **Keep.** Could eventually be renamed `omarchy-update-check`, but current name matches widget semantics. |
|
||||
| `omarchy-update-aur-pkgs` | Updates AUR packages with `yay -Sua` if foreign packages exist and AUR is reachable. | **Question.** Omarchy is package-backed now, but users may still install AUR packages. Keep for now. |
|
||||
@@ -282,36 +223,31 @@ scripts.
|
||||
|
||||
## Closed decisions
|
||||
|
||||
1. **System migrations run from the `omarchy` package**
|
||||
- `omarchy.install post_upgrade()` calls `omarchy-migrate-system`.
|
||||
- We do not need a separate system-migration ALPM hook from
|
||||
`omarchy-settings`.
|
||||
1. **Migrations run per-user from the update pipeline**
|
||||
- `omarchy update` runs `omarchy-migrate` after pacman finishes.
|
||||
- Package-time migration runners do not apply migrations inside pacman.
|
||||
- Every user has per-user migration markers, and migrations must be
|
||||
idempotent when they repair machine-wide state.
|
||||
|
||||
2. **Root vs user migrations stay separate**
|
||||
- Do not use `su {user}` from pacman to run user migrations.
|
||||
- User migrations need the user's real session and should be visible.
|
||||
- Pending user work is determined only by comparing `migrations/user/*.sh`
|
||||
against `~/.local/state/omarchy/migrations/user/`.
|
||||
|
||||
3. **Migration notification naming**
|
||||
2. **Migration notification naming**
|
||||
- The real helper is `omarchy-migrate-notify`.
|
||||
- `omarchy-update-user-notify` remains only as a hidden compatibility wrapper.
|
||||
|
||||
4. **Update pipeline ownership**
|
||||
3. **Update pipeline ownership**
|
||||
- `omarchy-update` owns the full update pipeline now.
|
||||
- `omarchy-update-perform` is only a hidden compatibility wrapper for
|
||||
`omarchy-update -y`.
|
||||
|
||||
5. **Mise remains in the blessed update path**
|
||||
4. **Mise remains in the blessed update path**
|
||||
- `omarchy-update-mise` intentionally runs as part of `omarchy update`.
|
||||
|
||||
6. **Orphan cleanup stays in the update path for now**
|
||||
5. **Orphan cleanup stays in the update path for now**
|
||||
- It is prompt-only and never removes packages noninteractively.
|
||||
|
||||
7. **Direct pacman user follow-up is based on actual migration state**
|
||||
6. **Direct pacman user follow-up is based on actual migration state**
|
||||
- Direct `sudo pacman -Syu` no longer uses a fake user-update marker.
|
||||
- User notifications are shown only when `omarchy-migrate --pending user`
|
||||
finds missing per-user migration state.
|
||||
- User notifications are shown only when `omarchy-migrate --pending` finds
|
||||
missing per-user migration state.
|
||||
|
||||
## Remaining concerns
|
||||
|
||||
|
||||
Reference in New Issue
Block a user