thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions
aman/docs/x11-ga
History
Exact
Thales Maciel f779b71e1b Use compileall for recursive compile checks 
Stop letting the explicit compile step overstate its coverage. The old py_compile globs only touched top-level modules, so syntax errors in nested packages could slip past make check and release-check.\n\nAdd a shared compile-check recipe in Makefile that runs python -m compileall -q src tests, and have both check and release-check use it so the local verification paths stay aligned. Update the GitHub Actions compile step and the matching runtime validation evidence doc to describe the same recursive compile contract.\n\nValidate with python3 -m compileall -q src tests, make check, and make release-check.
2026-03-14 18:37:25 -03:00
..
01-support-contract-and-ga-bar.md Add X11 GA roadmap and milestone definitions 2026-03-12 13:56:41 -03:00
02-portable-install-update-uninstall.md Close milestones 2 and 3 on Arch evidence 2026-03-12 20:29:42 -03:00
03-runtime-reliability-and-diagnostics.md Close milestones 2 and 3 on Arch evidence 2026-03-12 20:29:42 -03:00
04-first-run-ux-and-support-docs.md Close milestone 4 with review evidence 2026-03-12 18:57:57 -03:00
05-ga-candidate-validation-and-release.md Prepare the 1.0.0 GA release surface 2026-03-12 19:36:52 -03:00
first-run-review-notes.md Close milestone 4 with review evidence 2026-03-12 18:57:57 -03:00
ga-validation-report.md Align CI with the validated Ubuntu support floor 2026-03-14 15:45:21 -03:00
portable-validation-matrix.md Close milestones 2 and 3 on Arch evidence 2026-03-12 20:29:42 -03:00
README.md Close milestones 2 and 3 on Arch evidence 2026-03-12 20:29:42 -03:00
runtime-validation-report.md Use compileall for recursive compile checks 2026-03-14 18:37:25 -03:00

README.md

Aman X11 GA Roadmap

What is missing today

Aman is not starting from zero. It already has a working X11 daemon, a settings-first flow, diagnostics commands, Debian packaging, Arch packaging inputs, and a release checklist. What it does not have yet is a credible GA story for X11 users across mainstream distros.

The current gaps are:

  • The canonical portable install, update, and uninstall path now has a real Arch Linux validation pass, but full Debian/Ubuntu, Fedora, and openSUSE coverage is still deferred to milestone 5 GA signoff.
  • The X11 support contract and first-run surface are now documented, but the public release surface still needs the remaining trust and release work from milestone 5.
  • Validation matrices now exist for portable lifecycle and runtime reliability, but they are not yet filled with release-specific manual evidence across Debian/Ubuntu, Arch, Fedora, and openSUSE.
  • The repo-side trust surface now exists, but the public release page and final published artifact set still need to be made real.
  • Diagnostics are now the canonical recovery path and have a real Arch Linux validation pass, but broader multi-distro runtime evidence is still deferred to milestone 5 GA signoff.
  • The release checklist now includes GA signoff gates, but the project is still short of the broader legal, release-publication, and validation evidence needed for a credible public 1.0 release.

GA target

For this roadmap, GA means:

  • X11 only. Wayland is explicitly out of scope.
  • One canonical portable install path for end users.
  • Distro-specific runtime dependency guidance for major distro families.
  • Representative validation on Debian/Ubuntu, Arch, Fedora, and openSUSE.
  • A stable support contract, clear recovery path, and public release surface that a first-time user can trust.

"Any distro" does not mean literal certification of every Linux distribution. It means Aman ships one portable X11 installation path that works on mainstream distros with the documented runtime dependencies and system assumptions.

Support contract for GA

The GA support promise for Aman should be:

  • Linux desktop sessions running X11.
  • Mainstream distros with systemd --user available.
  • System CPython 3.10, 3.11, or 3.12 available for the portable installer.
  • Runtime dependencies installed from the distro package manager.
  • Service mode is the default end-user mode.
  • Foreground aman run remains a support and debugging path, not the primary daily-use path.

Native distro packages remain valuable, but they are secondary distribution channels. They are not the GA definition for X11 users on any distro.

Roadmap principles

  • Reliability beats feature expansion.
  • Simplicity beats distro-specific cleverness.
  • One canonical end-user path.
  • One canonical recovery path.
  • Public docs should explain the supported path before they explain internals.
  • Each milestone must reduce ambiguity, not just add artifacts.

Canonical delivery model

The roadmap assumes one portable release bundle for GA:

  • Release artifact: aman-x11-linux-<version>.tar.gz
  • Companion checksum file: aman-x11-linux-<version>.tar.gz.sha256
  • Installer entrypoint: install.sh
  • Uninstall entrypoint: uninstall.sh

The bundle installs Aman into user scope:

  • Versioned payload: ~/.local/share/aman/<version>/
  • Current symlink: ~/.local/share/aman/current
  • Command shim: ~/.local/bin/aman
  • User service: ~/.config/systemd/user/aman.service

The installer should use python3 -m venv --system-site-packages so Aman can rely on distro-provided GTK, X11, and audio bindings while still shipping its own Python package payload. This keeps the runtime simpler than a full custom bundle and avoids asking end users to learn uv.

Canonical recovery model

The roadmap also fixes the supported recovery path:

  • aman doctor is the first environment and config preflight.
  • aman self-check is the deeper readiness check for an installed system.
  • journalctl --user -u aman is the primary service log surface.
  • Foreground aman run --verbose is the support fallback when service mode is not enough.

Any future docs, tray copy, and release notes should point users to this same sequence.

Milestones

Cross-milestone acceptance scenarios

Every milestone should advance the same core scenarios:

  • Fresh install on a representative distro family.
  • First-run settings flow and first successful dictation.
  • Reboot or service restart followed by successful reuse.
  • Upgrade with config preservation.
  • Uninstall and cleanup.
  • Offline start with already-cached models.
  • Broken config or missing dependency followed by successful diagnosis and recovery.
  • Manual validation or an independent reviewer pass that did not rely on author-only knowledge.

Final GA release bar

Before declaring Aman GA for X11 users, all of the following should be true:

  • The support contract is public and unambiguous.
  • The portable installer and uninstaller are the primary documented user path.
  • The runtime and diagnostics path are reliable enough that failures are usually self-explanatory.
  • End-user docs include a 60-second quickstart, expected visible results, screenshots, and troubleshooting.
  • Release artifacts, checksums, license, project metadata, and support/contact surfaces are complete.
  • Validation evidence exists for Debian/Ubuntu, Arch, Fedora, and openSUSE.
  • The release is tagged and published as 1.0.0.

Non-goals

  • Wayland support.
  • New transcription or editing features that do not directly improve reliability, install simplicity, or diagnosability.
  • Full native-package parity across all distros as a GA gate.