Add X11 GA roadmap and milestone definitions

Capture the current GA gaps and define a portable X11 support contract so the release bar is explicit for mainstream distros.

Document five ordered milestones covering support policy, portable install/update/uninstall, runtime reliability and diagnostics, first-run UX/docs, and GA validation/release evidence.

Left generated artifacts (src/aman.egg-info) and prior readiness notes uncommitted.

2026-03-12 13:56:41 -03:00

3.3 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 all representative distro families.

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 the representative distro families.

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 successful install, upgrade, uninstall, and reinstall results.
A short troubleshooting section for partial installs, missing runtime dependencies, and service enable failures.

3.3 KiB Raw Blame History