thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions
aman/docs/persona-and-distribution.md
Thales Maciel dd2813340b Align CI with the validated Ubuntu support floor 
Stop implying that one Ubuntu 3.11 unit lane validates the full Linux support surface Aman documents.\n\nSplit CI into an Ubuntu CPython 3.10/3.11/3.12 unit-package matrix, a portable install plus doctor smoke lane, and a packaging lane gated on both. Add a reproducible ci_portable_smoke.sh helper with fake systemctl coverage, and force the installer onto /usr/bin/python3 so the smoke path uses the distro-provided GI and X11 Python packages it is meant to validate.\n\nUpdate the README, release/distribution docs, and Debian metadata to distinguish the automated Ubuntu CI floor from broader manual GA signoff families, and add the missing AppIndicator introspection package to the Ubuntu/Debian dependency lists.\n\nValidate with python3 -m unittest discover -s tests -p 'test_*.py', python3 -m py_compile src/*.py tests/*.py, and bash -n scripts/ci_portable_smoke.sh. The full xvfb-backed smoke could not be run locally in this sandbox because xvfb-run is unavailable.
2026-03-14 15:45:21 -03:00

3.8 KiB
Raw Blame History

Aman Target Persona and Distribution Strategy

Primary Persona: Desktop Professional

This is the canonical Aman user.

  • Uses Linux desktop daily on X11, across mainstream distros.
  • Wants fast dictation and rewriting without learning Python tooling.
  • Prefers GUI setup and tray usage over CLI.
  • Expects a simple end-user install plus a normal background service lifecycle.

Design implications:

  • End-user install path must not require uv.
  • Runtime defaults should work with minimal input.
  • Supported daily use should be a systemd --user service.
  • Foreground aman run should remain available for setup, support, and debugging.
  • Diagnostics should be part of the user workflow, not only developer tooling.
  • Documentation should distinguish current release channels from the long-term GA contract.

Secondary Persona: Power User

  • Comfortable with CLI, package internals, and model customization.
  • Uses advanced config, external APIs, or custom models.
  • Can run diagnostics and debug logs when needed.

Design implications:

  • Keep Make and Python workflows available.
  • Keep explicit expert-mode knobs in settings and config.
  • Keep docs for development separate from standard install docs.

Current Release Channels

The current release channels are:

  1. Current canonical end-user channel: portable X11 bundle (aman-x11-linux-<version>.tar.gz) published on https://git.thaloco.com/thaloco/aman/releases.
  2. Secondary packaged channel: Debian package (.deb) for Ubuntu/Debian users.
  3. Secondary maintainer channel: Arch package inputs (PKGBUILD + source tarball).
  4. Developer: wheel and sdist from python -m build.

GA Target Support Contract

For X11 GA, Aman supports:

  • X11 desktop sessions only.
  • System CPython 3.10, 3.11, or 3.12 for the portable installer.
  • Runtime dependencies installed from the distro package manager.
  • systemd --user as the supported daily-use path.
  • aman run as the foreground setup, support, and debugging path.
  • Automated validation floor on Ubuntu CI: CPython 3.10, 3.11, and 3.12 for unit/package coverage, plus portable install and aman doctor smoke with Ubuntu system python3.
  • Manual GA signoff families: Debian/Ubuntu, Arch, Fedora, openSUSE.
  • The recovery sequence aman doctor -> aman self-check -> journalctl --user -u aman -> aman run --verbose.

"Any distro" means mainstream distros that satisfy these assumptions. It does not mean native-package parity or exhaustive certification for every Linux variant.

Canonical end-user lifecycle

  • Install: extract the portable bundle and run ./install.sh.
  • Update: extract the newer portable bundle and run its ./install.sh.
  • Uninstall: run ~/.local/share/aman/current/uninstall.sh.
  • Purge uninstall: run ~/.local/share/aman/current/uninstall.sh --purge.
  • Recovery: aman doctor -> aman self-check -> journalctl --user -u aman -> aman run --verbose.

Out of Scope for X11 GA

  • Wayland production support.
  • Flatpak/snap-first distribution.
  • Cross-platform desktop installers outside Linux.
  • Native-package parity across every distro.

Release and Support Policy

  • App versioning follows SemVer starting with 1.0.0 for the X11 GA release.
  • Config schema versioning is independent (config_version in config).
  • Docs must always separate:
    • Current release channels
    • GA target support contract
    • Developer setup paths
  • The public support contract must always identify:
    • Supported environment assumptions
    • Daily-use service mode versus manual foreground mode
    • Canonical recovery sequence
    • Representative validation families
  • Public support and issue reporting currently use email only: thales@thalesmaciel.com
  • GA means the support contract, validation evidence, and release surface are consistent. It does not require a native package for every distro.