From 01a580f35974b4af2ac6edd84a5fcc91da56e27d Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Thu, 12 Mar 2026 13:56:41 -0300 Subject: [PATCH] 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. --- docs/x11-ga/01-support-contract-and-ga-bar.md | 57 ++++++++ .../02-portable-install-update-uninstall.md | 66 ++++++++++ .../03-runtime-reliability-and-diagnostics.md | 63 +++++++++ .../04-first-run-ux-and-support-docs.md | 68 ++++++++++ .../05-ga-candidate-validation-and-release.md | 60 +++++++++ docs/x11-ga/README.md | 123 ++++++++++++++++++ 6 files changed, 437 insertions(+) create mode 100644 docs/x11-ga/01-support-contract-and-ga-bar.md create mode 100644 docs/x11-ga/02-portable-install-update-uninstall.md create mode 100644 docs/x11-ga/03-runtime-reliability-and-diagnostics.md create mode 100644 docs/x11-ga/04-first-run-ux-and-support-docs.md create mode 100644 docs/x11-ga/05-ga-candidate-validation-and-release.md create mode 100644 docs/x11-ga/README.md diff --git a/docs/x11-ga/01-support-contract-and-ga-bar.md b/docs/x11-ga/01-support-contract-and-ga-bar.md new file mode 100644 index 0000000..7a9d893 --- /dev/null +++ b/docs/x11-ga/01-support-contract-and-ga-bar.md @@ -0,0 +1,57 @@ +# Milestone 1: Support Contract and GA Bar + +## Why this milestone exists + +The current project already has strong building blocks, but the public promise is still underspecified. Before adding more delivery or UX work, Aman needs a written support contract that tells users and implementers exactly what "GA for X11 users on any distro" means. + +## Problems it closes + +- The current docs do not define a precise supported environment. +- The default user lifecycle is ambiguous between a user service and foreground `aman run`. +- "Any distro" is too vague to test or support responsibly. +- The project lacks one GA checklist that later work can trace back to. + +## In scope + +- Define the supported X11 environment for GA. +- Define the representative distro validation families. +- Define the canonical end-user lifecycle: install, first launch, daily use, update, uninstall. +- Define the role of service mode versus foreground/manual mode. +- Define the canonical recovery sequence using diagnostics and logs. +- Define the final GA signoff checklist that the release milestone will complete. + +## Out of scope + +- Implementing the portable installer. +- Changing GUI behavior. +- Adding Wayland support. +- Adding new AI or STT capabilities that do not change supportability. + +## Dependencies + +- Current README and persona docs. +- Existing systemd user service behavior. +- Existing `doctor`, `self-check`, and verbose foreground run support. + +## Definition of done: objective + +- A public support matrix names Debian/Ubuntu, Arch, Fedora, and openSUSE as the representative GA distro families. +- The supported session assumptions are explicit: X11, `systemd --user`, and `python3` 3.10+ available for installer execution. +- The canonical end-user lifecycle is documented end to end. +- Service mode is defined as the default daily-use path. +- Foreground `aman run` is explicitly documented as a support/debug path. +- `aman doctor`, `aman self-check`, and `journalctl --user -u aman` are defined as the canonical recovery sequence. +- A GA checklist exists and every later milestone maps back to at least one item on it. + +## Definition of done: subjective + +- A new X11 user can quickly tell whether Aman supports their machine. +- An implementer can move to later milestones without reopening the product promise. +- The project no longer sounds broader than what it is prepared to support. + +## Evidence required to close + +- Updated README support section that matches the contract in this roadmap. +- A published support matrix doc or README table for environment assumptions and distro families. +- An updated release checklist that includes the GA signoff checklist. +- CLI help and support docs that use the same language for service mode, manual mode, and diagnostics. diff --git a/docs/x11-ga/02-portable-install-update-uninstall.md b/docs/x11-ga/02-portable-install-update-uninstall.md new file mode 100644 index 0000000..76b623f --- /dev/null +++ b/docs/x11-ga/02-portable-install-update-uninstall.md @@ -0,0 +1,66 @@ +# 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-.tar.gz`. +- Include `install.sh` and `uninstall.sh` in the release bundle. +- Use user-scoped installation layout: + - `~/.local/share/aman//` + - `~/.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. diff --git a/docs/x11-ga/03-runtime-reliability-and-diagnostics.md b/docs/x11-ga/03-runtime-reliability-and-diagnostics.md new file mode 100644 index 0000000..de6dbe3 --- /dev/null +++ b/docs/x11-ga/03-runtime-reliability-and-diagnostics.md @@ -0,0 +1,63 @@ +# Milestone 3: Runtime Reliability and Diagnostics + +## Why this milestone exists + +Once Aman is installed, the next GA risk is not feature depth. It is whether the product behaves predictably, fails loudly, and tells the user what to do next. This milestone turns diagnostics and recovery into a first-class product surface. + +## Problems it closes + +- Startup readiness and failure paths are not yet shaped into one user-facing recovery model. +- Diagnostics exist, but their roles are not clearly separated. +- Audio, hotkey, injection, and model-cache failures can still feel like implementation details instead of guided support flows. +- The release process does not yet require restart, recovery, or soak evidence. + +## In scope + +- Define `aman doctor` as the fast preflight check for config, runtime dependencies, hotkey validity, audio device resolution, and service prerequisites. +- Define `aman self-check` as the deeper installed-system readiness check, including managed model availability, writable cache locations, and end-to-end startup prerequisites. +- Make diagnostics return actionable messages with one next step, not generic failures. +- Standardize startup and runtime error wording across CLI output, service logs, tray notifications, and docs. +- Cover recovery paths for: + - broken config + - missing audio device + - hotkey registration failure + - X11 injection failure + - model download or cache failure + - service startup failure +- Add repeated-run validation, restart validation, and offline-start validation to release gates. +- Treat `journalctl --user -u aman` and `aman run --verbose` as the default support escalations after diagnostics. + +## Out of scope + +- New dictation features unrelated to supportability. +- Remote telemetry or cloud monitoring. +- Non-X11 backends. + +## Dependencies + +- Milestone 1 support contract. +- Milestone 2 portable install layout and service lifecycle. +- Existing diagnostics commands and systemd service behavior. + +## Definition of done: objective + +- `doctor` and `self-check` have distinct documented roles. +- The main end-user failure modes each produce an actionable diagnostic result or service-log message. +- No supported happy-path failure is known to fail silently. +- Restart after reboot and restart after service crash are part of the validation matrix. +- Offline start with already-cached models is part of the validation matrix. +- Release gates include repeated-run and recovery scenarios, not only unit tests. +- Support docs map each common failure class to a matching diagnostic command or log path. + +## Definition of done: subjective + +- When Aman fails, the user can usually answer "what broke?" and "what should I try next?" without reading source code. +- Daily use feels predictable even when the environment is imperfect. +- The support story feels unified instead of scattered across commands and logs. + +## Evidence required to close + +- Updated command help and docs for `doctor` and `self-check`. +- Diagnostic output examples for success, warning, and failure cases. +- A release validation report covering restart, offline-start, and representative recovery scenarios. +- Manual support runbooks that use diagnostics first and verbose foreground mode second. diff --git a/docs/x11-ga/04-first-run-ux-and-support-docs.md b/docs/x11-ga/04-first-run-ux-and-support-docs.md new file mode 100644 index 0000000..26e1d98 --- /dev/null +++ b/docs/x11-ga/04-first-run-ux-and-support-docs.md @@ -0,0 +1,68 @@ +# Milestone 4: First-Run UX and Support Docs + +## Why this milestone exists + +Even if install and runtime reliability are strong, Aman will not feel GA until a first-time user can understand it quickly. This milestone makes the supported path obvious and removes author-only knowledge from the initial experience. + +## Problems it closes + +- The current README mixes end-user, maintainer, and benchmarking material too early. +- There is no short happy path with an expected visible result. +- The repo has no screenshots or demo artifact showing that the desktop workflow is real. +- The support and diagnostics story is not yet integrated into first-run documentation. +- CLI help discoverability is weaker than the documented command surface. + +## In scope + +- Rewrite the README so the top of the file is end-user-first. +- Split end-user, developer, and maintainer material into clearly labeled sections or separate docs. +- Add a 60-second quickstart that covers: + - runtime dependency install + - portable Aman install + - first launch + - choosing a microphone + - triggering the first dictation + - expected tray or notification behavior + - expected injected text result +- Add a "validate your install" flow using `aman doctor` and `aman self-check`. +- Add screenshots for the settings window and tray menu. +- Add one short demo artifact showing a single install-to-dictation loop. +- Add troubleshooting for the common failures identified in milestone 3. +- Update `aman --help` so the top-level command surface is easy to discover. +- Align README language, tray copy, About/Help copy, and diagnostics wording. + +## Out of scope + +- New GUI features beyond what is needed for clarity and supportability. +- New branding or visual redesign unrelated to usability. +- Wayland onboarding. + +## Dependencies + +- Milestone 1 support contract. +- Milestone 2 install/update/uninstall flow. +- Milestone 3 diagnostics and recovery model. + +## Definition of done: objective + +- The README leads with the supported user path before maintainer content. +- A 60-second quickstart exists and includes an expected visible result. +- A documented install verification flow exists using diagnostics. +- Screenshots exist for the settings flow and tray surface. +- One short demo artifact exists for the happy path. +- Troubleshooting covers the top failure classes from milestone 3. +- Top-level CLI help exposes the main commands directly. +- Public docs consistently describe service mode, manual mode, and diagnostics. + +## Definition of done: subjective + +- A first-time evaluator can understand the product without guessing how it behaves. +- Aman feels like a user-facing desktop tool rather than an internal project. +- The docs reduce support load instead of creating new questions. + +## Evidence required to close + +- Updated README and linked support docs. +- Screenshots and demo artifact checked into the release or docs surface. +- A reviewer walk-through from someone who did not implement the docs rewrite. +- A short list of first-run questions found during review and how the docs resolved them. diff --git a/docs/x11-ga/05-ga-candidate-validation-and-release.md b/docs/x11-ga/05-ga-candidate-validation-and-release.md new file mode 100644 index 0000000..d107360 --- /dev/null +++ b/docs/x11-ga/05-ga-candidate-validation-and-release.md @@ -0,0 +1,60 @@ +# Milestone 5: GA Candidate Validation and Release + +## Why this milestone exists + +The final step to GA is not more feature work. It is proving that Aman has a real public release surface, complete support metadata, and evidence-backed confidence across the supported X11 environment. + +## Problems it closes + +- The project still looks pre-GA from a trust and release perspective. +- Legal and package metadata are incomplete. +- Release artifact publication and checksum expectations are not yet fully defined. +- The current release checklist does not yet capture all GA evidence. + +## In scope + +- Publish the first GA release as `1.0.0`. +- Add a real `LICENSE` file. +- Replace placeholder maintainer metadata and example URLs with real project metadata. +- Publish release artifacts and checksums for the portable X11 bundle. +- Keep native `.deb` and Arch package outputs as secondary artifacts when available. +- Publish release notes that describe the supported environment, install path, recovery path, and non-goals. +- Document support and issue-reporting channels. +- Complete the representative distro validation matrix. +- Add explicit GA signoff to the release checklist. + +## Out of scope + +- Expanding the GA promise beyond X11. +- Supporting every distro with a native package. +- New features that are not required to ship and support the release. + +## Dependencies + +- Milestones 1 through 4 complete. +- Existing packaging and release-check workflows. +- Final validation evidence from the representative distro families. + +## Definition of done: objective + +- The release version is `1.0.0`. +- A `LICENSE` file exists in the repository. +- `pyproject.toml`, package templates, and release docs contain real maintainer and project metadata. +- Portable release artifacts and checksum files are published. +- The release notes include install, update, uninstall, troubleshooting, and support/reporting guidance. +- A final validation report exists for Debian/Ubuntu, Arch, Fedora, and openSUSE. +- The release checklist includes and passes an explicit GA signoff section. + +## Definition of done: subjective + +- An external evaluator sees a maintained product with a credible release process. +- The release feels safe to recommend to X11 users without author hand-holding. +- The project no longer signals "preview" through missing metadata or unclear release mechanics. + +## Evidence required to close + +- Published `1.0.0` release page with artifacts and checksums. +- Final changelog and release notes. +- Completed validation report for the representative distro families. +- Updated release checklist with signed-off GA criteria. +- Public support/reporting instructions that match the shipped product. diff --git a/docs/x11-ga/README.md b/docs/x11-ga/README.md new file mode 100644 index 0000000..17572c1 --- /dev/null +++ b/docs/x11-ga/README.md @@ -0,0 +1,123 @@ +# 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: + +- No single distro-agnostic end-user install, update, and uninstall path. The repo documents a Debian package path and partial Arch support, but not one canonical path for X11 users on Fedora, openSUSE, or other mainstream distros. +- No explicit support contract for "X11 users on any distro." The current docs describe target personas and a package-first approach, but they do not define the exact environment that GA will support. +- No clear split between service mode and foreground/manual mode. The docs describe enabling a user service and also tell users to run `aman run`, which leaves the default lifecycle ambiguous. +- No representative distro validation matrix. There is no evidence standard that says which distros must pass install, first run, update, restart, and uninstall checks before release. +- Incomplete trust surface. The project still needs a real license file, real maintainer/contact metadata, real project URLs, published release artifacts, and public checksums. +- Incomplete first-run story. The product describes a settings window and tray workflow, but there is no short happy path, no expected-result walkthrough, and no visual proof that the experience is real. +- Diagnostics exist, but they are not yet the canonical recovery path for end users. `doctor` and `self-check` are present, but the docs do not yet teach users to rely on them first. +- Release process exists, but not yet as a GA signoff system. The current release checklist is a good base, but it does not yet enforce the broader validation and support evidence required for a 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 `python3` 3.10+ 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-.tar.gz` +- Companion checksum file: `aman-x11-linux-.tar.gz.sha256` +- Installer entrypoint: `install.sh` +- Uninstall entrypoint: `uninstall.sh` + +The bundle installs Aman into user scope: + +- Versioned payload: `~/.local/share/aman//` +- 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 + +1. [Milestone 1: Support Contract and GA Bar](./01-support-contract-and-ga-bar.md) + Lock the public promise, supported environment, and final signoff bar. +2. [Milestone 2: Portable Install, Update, and Uninstall](./02-portable-install-update-uninstall.md) + Build one reliable end-user lifecycle that works across mainstream X11 distros. +3. [Milestone 3: Runtime Reliability and Diagnostics](./03-runtime-reliability-and-diagnostics.md) + Make startup, failure handling, and recovery predictable. +4. [Milestone 4: First-Run UX and Support Docs](./04-first-run-ux-and-support-docs.md) + Turn the product from "documented by the author" into "understandable by a new user." +5. [Milestone 5: GA Candidate Validation and Release](./05-ga-candidate-validation-and-release.md) + Close the remaining trust, legal, release, and validation work for a public 1.0 launch. + +## 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 by someone who did not implement the feature. + +## 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.