omarchy-pkgs/pkgbuilds/elsewhen/.omarchy/README.md

elsewhen

Installs the Elsewhen world clock plugin from the v{pkgver} GitHub tag archive into /usr/share/omarchy/shell/plugins/omacom.elsewhen/ (the directory name is the plugin id the shell scans for, not the package name), plus LICENSE under /usr/share/licenses/elsewhen/ and the upstream README.md under /usr/share/doc/elsewhen/. The shell scans this directory alongside its bundled plugins.

package() copies an explicit allow-list (manifest.json, every *.qml and *.js, cities.json, world.json, worldclock-data.py), so tests/, .github/ and .gitignore never ship, and it fails the build if manifest.json is missing, does not declare omacom.elsewhen, or does not name a present Panel.qml as the entry point. An upstream release that adds a runtime file outside those patterns needs the allow-list extended here; the sync only moves versions and checksums. Every file is 0644: Panel.qml runs the script as python3 <plugin dir>/worldclock-data.py, so it needs no execute bit. No install hook: Omarchy restarts the shell after omarchy update, and nothing here may write into a user home. The script's only writes go to $XDG_CACHE_HOME/omacom-elsewhen/, which it creates itself at runtime.

Dependencies, cited as file: tool in the upstream tree:

• omarchy: ArcText.qml, Chip.qml, EarthRow.qml, Globe.qml, MiniGlobe.qml, MoonDot.qml, Panel.qml: import qs.Commons; EarthRow.qml, Globe.qml, Panel.qml: import qs.Ui. Owns /usr/share/omarchy and the shell plugin directory.
• quickshell: Globe.qml, Panel.qml: import Quickshell; Globe.qml, MiniGlobe.qml, Panel.qml: import Quickshell.Io (Process, FileView, StdioCollector).
• python: Panel.qml: python3 <plugin dir>/worldclock-data.py (the facts process). worldclock-data.py imports only json, os, sys, time, urllib.
• Left implicit as members of base, per Arch convention: bash (Panel.qml, Globe.qml: bash -c wraps every probe), coreutils (Panel.qml, Globe.qml: date, one probe per refresh), systemd (Panel.qml: timedatectl show, timedatectl list-timezones, each with a fallback: /etc/localtime for the home zone and find /usr/share/zoneinfo for the catalog), sed and grep (Panel.qml: the symlink target of /etc/localtime and the zoneinfo catalog filter), findutils and tzdata (that fallback; worldclock-data.py: /usr/share/zoneinfo/zone1970.tab). omarchy cannot run without any of them either.
• Not a dependency: iso-codes. Only tests/currency_check.py reads /usr/share/iso-codes/json, to validate the currency table before a release; the runtime never touches it.

Release tracking: bin/sync-upstream follows omacom/elsewhen through the upstream.watch.github provider, which reads the GitHub Releases feed (drafts and prereleases excluded; a tag with no published Release is not seen) and matches exactly vX.Y.Z, the grammar upstream's scripts/set-version.sh enforces. A newer release rewrites pkgver, resets pkgrel to 1, fetches archive/refs/tags/v{pkgver}.tar.gz again and rewrites sha256sums from the download. The Release's published_at is what lets min_release_age: 24h hold a fresh release for a day; release_ring: fast builds it straight to rc and stable as well as edge.

The watch only moves on a version increase, so the first release's digest is filled in by hand (curl -fsSL <archive url> | sha256sum), which is why the recipe carries a placeholder until the v0.1.0 tag exists. Until upstream has published at least one Release, the watch finds nothing and fails the scheduled sync-upstream run for every package in the batch, so this recipe stays a draft until then.