thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions
aman/docs/persona-and-distribution.md
Thales Maciel 31a1e069b3
Prepare the 1.0.0 GA release surface 
Add the repo-side pieces for milestone 5: MIT licensing, real maintainer and forge metadata, a public support doc, 1.0.0 release notes, release-prep tooling, and CI uploads for the full candidate artifact set.

Keep source-tree version surfaces honest by reading the local project version in the CLI and About dialog, and cover the new release-prep plus version-fallback behavior with focused tests.

Document where raw validation evidence belongs, add the GA validation rollup, and archive the latest readiness review. Milestone 5 remains open until the forge release page is published and the milestone 2 and 3 matrices are filled with linked manual evidence.

Validation: PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'; PYTHONPATH=src python3 -m unittest tests.test_release_prep tests.test_portable_bundle tests.test_aman_cli tests.test_config_ui; python3 -m py_compile src/*.py tests/*.py; PYTHONPATH=src python3 -m aman version
2026-03-12 19:36:52 -03:00

3.6 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.
  • Representative validation across Debian/Ubuntu, Arch, Fedora, and 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.