moonarch-pkgbuilds/DECISIONS.md

Decisions

2026-06-10 – Rust/Go packages: -git → no-suffix tag-build (match what ships)

• Who: Dominik, ClaudeCode
• Why: moonlock-git/moongreet-git/moonset-git/sshfsc-git carried the -git suffix (Arch convention: VCS package, user builds HEAD locally) but the registry ships pre-built binaries — the user never builds. The suffix lied about what is distributed. corsairctl already did it right: no suffix, build from a versioned git tag (#tag=v$pkgver) — the official-Arch-repo model (versioned source, built centrally, distributed as binary).
• Tradeoffs: A -bin style (project CI builds the binary, PKGBUILD installs only a release asset) was considered but rejected: it needs new build infra in each project repo, whereas tag-build is the smallest change to the existing two-stage CI and corsairctl already proves the pattern. The build stays in CI (no OOM-relevant change). Downside: per-package update-pkgver now reads the latest tag instead of git describe.
• How: In moonarch-pkgbuilds, git mv <name>-git <name>; PKGBUILD drops pkgver(), sets fixed pkgver = latest tag, source=...#tag=v$pkgver, pkgname without suffix, pkgrel=1, plus replaces=('<name>-git') + conflicts=('<name>-git') for clean client migration on pacman -Syu. moongreet keeps epoch=1 (2026-04-28 rollback) and its install hook. corsairctl added as-is (already tag-style). moonarch-git depends updated to the new names (pkgrel 12 → 13). Per-project update-pkgver.yaml switched to tag-trigger + git describe --tags --abbrev=0. Old -git registry versions deleted manually (the name change defeats the auto zombie-cleanup). Scope: sshfsc deferred (only tag v0.1.0, HEAD 11 commits ahead — needs a fresh tag first); sweet-cursors stays -git (no version tags upstream).

2026-05-04 – moonarch-git: skip wlsunset in global enable loop

• Who: Dominik, ClaudeCode
• Why: PKGBUILD's blanket loop over defaults/etc/systemd/user/*.service created /etc/systemd/user/graphical-session.target.wants/wlsunset.service — a global-scope symlink. The waybar nightlight toggle calls systemctl --user disable wlsunset, which only touches user-scope symlinks; the global one persists, so the filter came back on every reboot. Fix coordinates with moonarch repo (post-install.sh and CLAUDE.md updates) — see moonarch/DECISIONS.md 2026-05-04 entry.
• Tradeoffs: A whitelist of services-to-enable (instead of blacklist) would be cleaner long-term, but the project ships exactly one toggle-able user service today; a skip_enable array reads more clearly against the existing loop. pre_upgrade() cleanup is conservative: removes only the wlsunset wants-symlink, leaves the unit file itself.
• How: PKGBUILD package() — symlink loop now consults skip_enable=("wlsunset.service") and skips matching basenames. moonarch.install pre_upgrade() — deletes pre-existing /etc/systemd/user/graphical-session.target.wants/wlsunset.service so installed systems migrate cleanly. pkgrel bumped 11 → 12 so existing installs see the fix on next pacman -Syu; otherwise the registry would carry a same-versioned package and clients would skip the upgrade.

2026-04-28 – Bump epoch on moongreet-git after upstream version rollback

• Who: Dominik, ClaudeCode
• Why: pacman -Syu warned that local moongreet-git 0.10.0.r0.gce9f219-3 is "newer" than the moonarch registry's 0.8.6.r0.gb9b6f50-1. Cause: greetd-moongreet upstream was tagged v0.9.0 and v0.10.0 early on, then the tag history continued with v0.8.4 → v0.8.5 → v0.8.6 patches on top — a deliberate downgrade of the version line. pkgver() uses git describe --long --tags, which now returns 0.8.6.r0.gb9b6f50 at HEAD, but any system that built moongreet before the tag rollback still has the higher-sorting 0.10.0 installed. Without an epoch bump, those systems will never accept the registry's 0.8.x as an upgrade.
• Tradeoffs: Re-tagging upstream to leapfrog past v0.10.0 (e.g. v0.11.0) would also resolve the mismatch and avoid the epoch — but it would create a fake version that doesn't reflect the actual feature scope, and we'd be permanently chasing the v0.10.0 ghost on every future bump. Epoch is the canonical pacman mechanism for exactly this situation; one-time cost, no upstream lie.
• How: epoch=1 added to moongreet-git/PKGBUILD, pkgrel bumped 3 → 4 to retrigger CI.

2026-04-28 – Bump epoch on sweet-cursors-git to overrule AUR-built local installs

• Who: Dominik, ClaudeCode
• Why: pacman -Syu warned that local sweet-cursors-git r445.1d92ac7-1 is "newer" than the moonarch registry's r1.4b49c35-2. Cause: our Gitea fork (nevaforget/Sweet-cursors) is a one-shot snapshot of EliverLara/Sweet's kde/cursors/Sweet-cursors/ from 2025-09-28 with a single init commit, so pkgver() always evaluates to r1. The local r445 came from the AUR package by Gigas002 (source: github.com/Gigas002/Sweet#cursors, 445 commits, actively maintained, last cursor change 2026-03-02). Without an epoch bump, vercmp would flag the registry as a downgrade on every system that ever installed via paru/AUR.
• Tradeoffs: Switching the PKGBUILD source to Gigas002/Sweet#cursors would track upstream and avoid the version mismatch entirely, but requires inkscape + xorg-xcursorgen makedeps and a non-trivial SVG-compile build step in CI. Cursor changes upstream are minimal in practice (one fix in 6 months), so the maintenance value is low. Keeping the snapshot keeps the build trivial and the source tiny — at the cost of being permanently frozen at the September 2025 state. Documented in the fork's README.
• How: epoch=1 added to sweet-cursors-git/PKGBUILD, pkgrel bumped 2 → 3 to retrigger CI. Added README.md to the nevaforget/Sweet-cursors Gitea repo explaining the snapshot rationale and pointing to Gigas002/Sweet for users who want a maintained variant.

2026-04-23 – Rust PKGBUILDs honour CARGO_TARGET_DIR

• Who: Dominik, ClaudeCode
• Why: The act_runner container sets CARGO_TARGET_DIR=/cache/target (for cross-build cache persistence), but moongreet-git/moonlock-git/moonset-git package() hardcoded target/release/<bin>. Run 87 compiled for 8 min and then failed at install: cannot stat 'target/release/moongreet' because the binary actually lived in /cache/target/release/. Silent until today because earlier builds pre-date the env var.
• Tradeoffs: None meaningful — the fallback ${CARGO_TARGET_DIR:-target} preserves local makepkg builds (no env var → still reads from ./target/).
• How: Patched install -Dm755 in all three Rust-app PKGBUILDs to use "${CARGO_TARGET_DIR:-target}/release/<bin>".

2026-04-23 – Single-threaded, low-priority build in CI to keep the Gitea host alive

• Who: Dominik, ClaudeCode
• Why: The act_runner container shares CPU/RAM/I/O with the Gitea host (network-host mode, no resource limits). Parallel Rust builds OOM-kill or thrash the host: run 86 (2026-04-23, moongreet-git 0.8.3.r1) stopped mid-compile at Compiling gio v0.22.2 with no error, and gitea HTTPS was unreachable for ~11 min. Same pattern on 2026-04-20. Runner-side resource limits would be better, but require host-side config changes; a pipeline-side fix is portable and low-risk.
• Tradeoffs: Builds are slower — single-threaded cargo compile of a moon* project takes ~2–3× as long. nice -n 19 + ionice -c 3 further delay the build when the host is busy, but that's the point. Slow build beats downed host.
• How: build-and-publish.yaml exports CARGO_BUILD_JOBS=1 and MAKEFLAGS=-j1 before makepkg, and wraps makepkg with nice -n 19 ionice -c 3. Affects every package build in the matrix.

2026-04-21 – moonarch-git becomes a full meta-package (hard deps on all Arch-repo essentials + own registry siblings)

• Who: Dominik, ClaudeCode
• Why: moonarch-git listed moongreet-git/moonlock-git/moonset-git only as optdepends and omitted most Arch-repo essentials (wlsunset, networkmanager, bluez, xwayland-satellite, file-manager stack, zsh plugins, CLI tools, …) entirely — they lived only in packages/official.txt. paru -S moonarch-git on a fresh system therefore produced a desktop with no greeter, no lockscreen, no power menu, no nightlight, no network manager, no portals — a non-functional Moonarch. Split source of truth between PKGBUILD deps and txt files caused continuous drift (e.g. walker-bin was missing from both).
• Tradeoffs: moonarch-git is now chunky — installing it pulls ~60 packages (vs ~20 before). Acceptable because this is exactly what every Moonarch system needs; a leaner package just shifted the install work to imperative scripts that silently failed. AUR packages cannot be hard depends= (pacman can't resolve AUR), so they stay in packages/aur.txt and post-install.sh pulls them explicitly. optdepends= was slashed to real extras (docker, rustup for dev, waterfox) — no more mirroring of aur.txt there.
• How: Added to depends=: moongreet-git, moonlock-git, moonset-git, xwayland-satellite, libnotify, foot-terminfo, wlsunset, nwg-look, awww, libpulse, gst-plugin-pipewire, networkmanager + nm-applet + nm-openvpn + openvpn, bluez, gvfs + gvfs-{dnssd,mtp,smb}, udisks2, ntfs-3g, xdg-desktop-portal-{gnome,gtk}, qt6-5compat, zsh-{autosuggestions,syntax-highlighting}, bat, btop, eza, fastfetch, fd, fzf, lazygit, ripgrep, neovim, git, fwupd, ufw. Removed from optdepends=: all Moonarch ecosystem packages (now hard deps), all AUR packages (post-install.sh pulls from aur.txt), and already-depended Arch-repo packages. pkgrel bumped 9 → 10.

2026-04-20 – Registry is the only install path; drop paru --pkgbuilds

• Who: Dominik, ClaudeCode
• Why: Two parallel mechanisms for finding moonarch packages (the Arch registry via [moonarch] in pacman.conf, and paru's PKGBUILD-repo via [moonarch-pkgbuilds] in paru.conf) created ambiguous state: paru -S resolves from whichever has a matching version first, and diagnostics have to account for both. With the registry DB now stable (see zombie fix below), the PKGBUILD-repo path is redundant.
• Tradeoffs: No more local-build fallback when the registry is broken — but when the registry is broken, the real fix is to repair it, not to mask the problem with a second mechanism. Existing systems need their /etc/paru.conf cleaned once (hook handles that on next moonarch-git upgrade).
• How: moonarch.install post_install now deletes Mode = arp and the [moonarch-pkgbuilds] section from /etc/paru.conf instead of writing them. moonarch/scripts/post-install.sh and transform.sh no longer configure paru.conf or call paru -Syu --pkgbuilds; they run pacman -Sy + paru -S moonarch-git (registry only).

2026-04-20 – CI wipes all package versions before upload to kill DB zombies

• Who: Dominik, ClaudeCode
• Why: paru -Syu stopped offering moonarch-git updates after the r99 → r105 pkgver bump. Root cause: Gitea's Arch registry updates moonarch.db incrementally on upload, but does not evict old entries when a pkgver changes. r99 lingered in the DB as a zombie — file already 404, but desc/sig still present — so clients saw r99 as "latest" and never got r105. Not a one-off: every future pkgver bump would repeat the issue.
• Tradeoffs: Delete-before-upload adds an HTTP round-trip per package and requires read:package on the registry token (write:package was already there for upload). Alternative was an admin-side DB scrub per zombie — unscalable and hostile to the user.
• How: build-and-publish.yaml now lists every existing version of each built package via GET /api/v1/packages/{owner}?type=arch&q={name} and DELETEs them before the upload loop. jq installed on the runner as a dependency of the listing parser. The per-upload DELETE of the exact new version was removed (redundant).

2026-04-20 – Register moongreet/moonset/sweet-cursors in the Arch registry

• Who: Dominik, ClaudeCode
• Why: These three packages were missing entirely from the registry — their last pkgver-bumps landed before the build-and-publish CI fixes (makedepends install, source-based PKGBUILD parse, multi-artifact upload). Without a new PKGBUILD change, the workflow never re-triggered, so they stayed absent.
• Tradeoffs: Bumping pkgrel manually is a one-shot push. Alternative (wait for the next real upstream change) would have left packages uninstallable indefinitely.
• How: Bumped pkgrel in each PKGBUILD, single commit, triggered the build-and-publish workflow.