thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions
aman/docs/x11-ga/02-portable-install-update-uninstall.md
Thales Maciel b4a3d446fa
Some checks failed
ci / test-and-build (push) Has been cancelled
Details
Close milestones 2 and 3 on Arch evidence 
Record the user-reported Arch X11 validation pass and thread it through the portable and runtime validation matrices.

Adjust the milestone 2 and 3 closeout wording so one fully validated representative distro family is enough for now, while keeping Debian/Ubuntu, Fedora, and openSUSE coverage as an explicit milestone 5 GA signoff requirement.

Update the roadmap and GA validation rollup to mark milestones 2 and 3 complete for now rather than fully GA-complete, and archive the raw Arch evidence in user-readiness/1773357669.md.

Validation: documentation consistency review only; no code or behavior changes were made.
2026-03-12 20:29:42 -03:00

3.6 KiB
Raw Blame History

Milestone 2: Portable Install, Update, and Uninstall

Why this milestone exists

GA for X11 users on any distro requires one install path that does not depend on Debian packaging, Arch packaging, or Python workflow knowledge. This milestone defines that path and keeps it intentionally boring.

Problems it closes

  • End-user installation is currently distro-specific or developer-oriented.
  • Update and uninstall behavior are not defined for a portable install path.
  • The current docs do not explain where Aman lives on disk, how upgrades work, or what gets preserved.
  • Runtime dependencies are listed, but the install experience is not shaped around them.

In scope

  • Ship one portable release bundle: aman-x11-linux-<version>.tar.gz.
  • Include install.sh and uninstall.sh in the release bundle.
  • Use user-scoped installation layout:
    • ~/.local/share/aman/<version>/
    • ~/.local/share/aman/current
    • ~/.local/bin/aman
    • ~/.config/systemd/user/aman.service
  • Use python3 -m venv --system-site-packages so the Aman payload is self-contained while GTK, X11, and audio bindings come from the distro.
  • Make install.sh handle both fresh install and upgrade.
  • Preserve config on upgrade by default.
  • Make uninstall.sh remove the user service, command shim, and installed payload while preserving config and caches by default.
  • Add --purge mode to uninstall config and caches as an explicit opt-in.
  • Publish distro-specific runtime dependency instructions for Debian/Ubuntu, Arch, Fedora, and openSUSE.
  • Validate the portable flow on at least one representative distro family for milestone closeout, with full Debian/Ubuntu, Arch, Fedora, and openSUSE coverage deferred to milestone 5 GA signoff.

Out of scope

  • Replacing native .deb or Arch package inputs.
  • Shipping a fully bundled Python runtime.
  • Supporting non-systemd service managers as GA.
  • Adding auto-update behavior.

Dependencies

  • Milestone 1 support contract and lifecycle definition.
  • Existing packaging scripts as a source of dependency truth.
  • Existing systemd user service as the base service model.

Definition of done: objective

  • End users do not need uv, pip, or wheel-building steps.
  • One documented install command sequence exists for all supported distros.
  • One documented update command sequence exists for all supported distros.
  • One documented uninstall command sequence exists for all supported distros.
  • Install and upgrade preserve a valid existing config unless the user explicitly resets it.
  • Uninstall removes the service cleanly and leaves no broken aman command in PATH.
  • Dependency docs cover Debian/Ubuntu, Arch, Fedora, and openSUSE with exact package names.
  • Install, upgrade, uninstall, and reinstall are each validated on at least one representative distro family for milestone closeout, with full four-family coverage deferred to milestone 5 GA signoff.

Definition of done: subjective

  • The install story feels like a normal end-user workflow instead of a developer bootstrap.
  • Upgrades feel safe and predictable.
  • A support engineer can describe the filesystem layout and cleanup behavior in one short answer.

Evidence required to close

  • Release bundle contents documented and reproducible from CI or release tooling.
  • Installer and uninstaller usage docs with example output.
  • A distro validation matrix showing one fully successful representative distro pass for milestone closeout, with full four-family coverage deferred to milestone 5 GA signoff.
  • A short troubleshooting section for partial installs, missing runtime dependencies, and service enable failures.