Close milestones 2 and 3 on Arch evidence
Some checks failed
ci / test-and-build (push) Has been cancelled
Some checks failed
ci / test-and-build (push) Has been cancelled
Record the user-reported Arch X11 validation pass and thread it through the portable and runtime validation matrices. Adjust the milestone 2 and 3 closeout wording so one fully validated representative distro family is enough for now, while keeping Debian/Ubuntu, Fedora, and openSUSE coverage as an explicit milestone 5 GA signoff requirement. Update the roadmap and GA validation rollup to mark milestones 2 and 3 complete for now rather than fully GA-complete, and archive the raw Arch evidence in user-readiness/1773357669.md. Validation: documentation consistency review only; no code or behavior changes were made.
This commit is contained in:
parent
31a1e069b3
commit
b4a3d446fa
7 changed files with 102 additions and 39 deletions
|
|
@ -26,7 +26,9 @@ GA for X11 users on any distro requires one install path that does not depend on
|
|||
- 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.
|
||||
- Validate the portable flow on at least one representative distro family for
|
||||
milestone closeout, with full Debian/Ubuntu, Arch, Fedora, and openSUSE
|
||||
coverage deferred to milestone 5 GA signoff.
|
||||
|
||||
## Out of scope
|
||||
|
||||
|
|
@ -50,7 +52,9 @@ GA for X11 users on any distro requires one install path that does not depend on
|
|||
- 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.
|
||||
- Install, upgrade, uninstall, and reinstall are each validated on at least one
|
||||
representative distro family for milestone closeout, with full four-family
|
||||
coverage deferred to milestone 5 GA signoff.
|
||||
|
||||
## Definition of done: subjective
|
||||
|
||||
|
|
@ -62,5 +66,7 @@ GA for X11 users on any distro requires one install path that does not depend on
|
|||
|
||||
- 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 distro validation matrix showing one fully successful representative distro
|
||||
pass for milestone closeout, with full four-family coverage deferred to
|
||||
milestone 5 GA signoff.
|
||||
- A short troubleshooting section for partial installs, missing runtime dependencies, and service enable failures.
|
||||
|
|
|
|||
|
|
@ -24,7 +24,9 @@ Once Aman is installed, the next GA risk is not feature depth. It is whether the
|
|||
- X11 injection failure
|
||||
- model download or cache failure
|
||||
- service startup failure
|
||||
- Add repeated-run validation, restart validation, and offline-start validation to release gates.
|
||||
- Add repeated-run validation, restart validation, and offline-start validation
|
||||
to release gates, and manually validate them on at least one representative
|
||||
distro family for milestone closeout.
|
||||
- Treat `journalctl --user -u aman` and `aman run --verbose` as the default support escalations after diagnostics.
|
||||
|
||||
## Out of scope
|
||||
|
|
@ -44,8 +46,12 @@ Once Aman is installed, the next GA risk is not feature depth. It is whether the
|
|||
- `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.
|
||||
- Restart after reboot and restart after service crash are part of the
|
||||
validation matrix and are manually validated on at least one representative
|
||||
distro family for milestone closeout.
|
||||
- Offline start with already-cached models is part of the validation matrix and
|
||||
is manually validated on at least one representative distro family for
|
||||
milestone closeout.
|
||||
- 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.
|
||||
|
||||
|
|
@ -59,5 +65,8 @@ Once Aman is installed, the next GA risk is not feature depth. It is whether the
|
|||
|
||||
- Updated command help and docs for `doctor` and `self-check`, including a public runtime recovery guide.
|
||||
- Diagnostic output examples for success, warning, and failure cases.
|
||||
- A release validation report covering restart, offline-start, and representative recovery scenarios.
|
||||
- A release validation report covering restart, offline-start, and
|
||||
representative recovery scenarios, with one real distro pass sufficient for
|
||||
milestone closeout and full four-family coverage deferred to milestone 5 GA
|
||||
signoff.
|
||||
- Manual support runbooks that use diagnostics first and verbose foreground mode second.
|
||||
|
|
|
|||
|
|
@ -6,11 +6,16 @@ Aman is not starting from zero. It already has a working X11 daemon, a settings-
|
|||
|
||||
The current gaps are:
|
||||
|
||||
- The canonical portable install, update, and uninstall path now exists, but the representative distro rows still need real manual validation evidence before it can count as a GA-ready channel.
|
||||
- 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.
|
||||
- Incomplete trust surface. The project still needs a real license file, real maintainer/contact metadata, real project URLs, published release artifacts, and public checksums.
|
||||
- Diagnostics are now the canonical recovery path, but milestone 3 still needs release-specific X11 evidence for restart, offline-start, tray diagnostics, and recovery scenarios.
|
||||
- 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
|
||||
|
|
@ -84,20 +89,21 @@ Any future docs, tray copy, and release notes should point users to this same se
|
|||
`docs/persona-and-distribution.md` now separates current release channels from
|
||||
the GA contract; `docs/release-checklist.md` now includes GA signoff gates;
|
||||
CLI help text now matches the same service/support language.
|
||||
- [ ] [Milestone 2: Portable Install, Update, and Uninstall](./02-portable-install-update-uninstall.md)
|
||||
Implementation landed on 2026-03-12: the portable bundle, installer,
|
||||
uninstaller, docs, and automated lifecycle tests are in the repo. Leave this
|
||||
milestone open until the representative distro rows in
|
||||
[`portable-validation-matrix.md`](./portable-validation-matrix.md) are filled
|
||||
with real manual validation evidence.
|
||||
- [ ] [Milestone 3: Runtime Reliability and Diagnostics](./03-runtime-reliability-and-diagnostics.md)
|
||||
Implementation landed on 2026-03-12: `doctor` and `self-check` now have
|
||||
distinct read-only roles, runtime failures log stable IDs plus next steps,
|
||||
`make runtime-check` is part of the release surface, and the runtime recovery
|
||||
guide plus validation report now exist. Leave this milestone open until the
|
||||
release-specific manual rows in
|
||||
[`runtime-validation-report.md`](./runtime-validation-report.md) are filled
|
||||
with real X11 validation evidence.
|
||||
- [x] [Milestone 2: Portable Install, Update, and Uninstall](./02-portable-install-update-uninstall.md)
|
||||
Status: completed for now on 2026-03-12. Evidence: the portable bundle,
|
||||
installer, uninstaller, docs, and automated lifecycle tests are in the repo,
|
||||
and the Arch Linux row in [`portable-validation-matrix.md`](./portable-validation-matrix.md)
|
||||
is now backed by [`user-readiness/1773357669.md`](../../user-readiness/1773357669.md).
|
||||
Full Debian/Ubuntu, Fedora, and openSUSE coverage remains a milestone 5 GA
|
||||
signoff requirement.
|
||||
- [x] [Milestone 3: Runtime Reliability and Diagnostics](./03-runtime-reliability-and-diagnostics.md)
|
||||
Status: completed for now on 2026-03-12. Evidence: `doctor` and
|
||||
`self-check` have distinct roles, runtime failures log stable IDs plus next
|
||||
steps, `make runtime-check` is part of the release surface, and the Arch
|
||||
Linux runtime rows in [`runtime-validation-report.md`](./runtime-validation-report.md)
|
||||
are now backed by [`user-readiness/1773357669.md`](../../user-readiness/1773357669.md).
|
||||
Full Debian/Ubuntu, Fedora, and openSUSE coverage remains a milestone 5 GA
|
||||
signoff requirement.
|
||||
- [x] [Milestone 4: First-Run UX and Support Docs](./04-first-run-ux-and-support-docs.md)
|
||||
Status: completed on 2026-03-12. Evidence: the README is now end-user-first,
|
||||
first-run assets live under `docs/media/`, deep config and maintainer content
|
||||
|
|
@ -110,8 +116,8 @@ Any future docs, tray copy, and release notes should point users to this same se
|
|||
maintainer and forge URLs, `LICENSE`, `SUPPORT.md`, `docs/releases/1.0.0.md`,
|
||||
`make release-prep`, and [`ga-validation-report.md`](./ga-validation-report.md)
|
||||
now exist. Leave this milestone open until the release page is published and
|
||||
the milestone 2 and 3 validation matrices are filled with linked raw
|
||||
evidence.
|
||||
the remaining Debian/Ubuntu, Fedora, and openSUSE rows are filled in the
|
||||
milestone 2 and 3 validation matrices.
|
||||
|
||||
## Cross-milestone acceptance scenarios
|
||||
|
||||
|
|
|
|||
|
|
@ -20,6 +20,9 @@ state.
|
|||
- Reference those timestamped files from the `Notes` columns in:
|
||||
- [`portable-validation-matrix.md`](./portable-validation-matrix.md)
|
||||
- [`runtime-validation-report.md`](./runtime-validation-report.md)
|
||||
- For milestone 2 and 3 closeout, one fully validated representative distro
|
||||
family is enough for now. Full Debian/Ubuntu, Arch, Fedora, and openSUSE
|
||||
coverage remains a milestone 5 GA signoff requirement.
|
||||
|
||||
## Release metadata
|
||||
|
||||
|
|
@ -46,9 +49,10 @@ state.
|
|||
|
||||
| Area | Status | Evidence |
|
||||
| --- | --- | --- |
|
||||
| Milestone 2 portable lifecycle | Pending | Fill `portable-validation-matrix.md` and link raw timestamped evidence |
|
||||
| Milestone 3 runtime reliability | Pending | Fill `runtime-validation-report.md` and link raw timestamped evidence |
|
||||
| Milestone 2 portable lifecycle | Complete for now | Arch row in `portable-validation-matrix.md` plus [`user-readiness/1773357669.md`](../../user-readiness/1773357669.md) |
|
||||
| Milestone 3 runtime reliability | Complete for now | Arch runtime rows in `runtime-validation-report.md` plus [`user-readiness/1773357669.md`](../../user-readiness/1773357669.md) |
|
||||
| Milestone 4 first-run UX/docs | Complete | `first-run-review-notes.md` and `user-readiness/1773352170.md` |
|
||||
| Release metadata and support surface | Repo-complete | `LICENSE`, `SUPPORT.md`, `pyproject.toml`, packaging templates |
|
||||
| Release artifacts and checksums | Repo-complete | `make release-prep`, `dist/SHA256SUMS`, `docs/releases/1.0.0.md` |
|
||||
| Full four-family GA validation | Pending | Complete the remaining Debian/Ubuntu, Fedora, and openSUSE rows in both validation matrices |
|
||||
| Published release page | Pending | Publish `v1.0.0` on the forge release page and attach the prepared artifacts |
|
||||
|
|
|
|||
|
|
@ -17,8 +17,9 @@ Completed on 2026-03-12:
|
|||
|
||||
## Manual distro validation
|
||||
|
||||
These rows must be filled with real results before milestone 2 can be closed as
|
||||
fully complete for GA evidence.
|
||||
One fully validated representative distro family is enough to close milestone 2
|
||||
for now. Full Debian/Ubuntu, Arch, Fedora, and openSUSE coverage remains a
|
||||
milestone 5 GA signoff requirement.
|
||||
|
||||
Store raw evidence for each distro pass in `user-readiness/<linux-timestamp>.md`
|
||||
and reference that file in the `Notes` column.
|
||||
|
|
@ -26,7 +27,7 @@ and reference that file in the `Notes` column.
|
|||
| Distro family | Fresh install | First service start | Upgrade | Uninstall | Reinstall | Reboot or service restart | Missing dependency recovery | Conflict with prior package install | Reviewer | Status | Notes |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| Debian/Ubuntu | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | |
|
||||
| Arch | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | |
|
||||
| Arch | Pass | Pass | Pass | Pass | Pass | Pass | Pass | Pass | User | Complete for now | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md) |
|
||||
| Fedora | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | |
|
||||
| openSUSE | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | |
|
||||
|
||||
|
|
|
|||
|
|
@ -31,8 +31,9 @@ Completed on 2026-03-12:
|
|||
|
||||
## Manual X11 validation
|
||||
|
||||
These rows must be filled with release-specific evidence before milestone 3 can
|
||||
be closed as complete for GA signoff.
|
||||
One representative distro family with real runtime validation is enough to
|
||||
close milestone 3 for now. Full Debian/Ubuntu, Arch, Fedora, and openSUSE
|
||||
coverage remains a milestone 5 GA signoff requirement.
|
||||
|
||||
Store raw evidence for each runtime validation pass in
|
||||
`user-readiness/<linux-timestamp>.md` and reference that file in the `Notes`
|
||||
|
|
@ -40,9 +41,9 @@ column.
|
|||
|
||||
| Scenario | Debian/Ubuntu | Arch | Fedora | openSUSE | Reviewer | Status | Notes |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| Service restart after a successful install | Pending | Pending | Pending | Pending | Pending | Pending | Verify `systemctl --user restart aman` returns to the tray/ready state |
|
||||
| Reboot followed by successful reuse | Pending | Pending | Pending | Pending | Pending | Pending | Validate recovery after a real session restart |
|
||||
| Offline startup with an already-cached model | Pending | Pending | Pending | Pending | Pending | Pending | Disable network, then confirm the cached path still starts |
|
||||
| Missing runtime dependency recovery | Pending | Pending | Pending | Pending | Pending | Pending | Remove one documented dependency, verify diagnostics point to the correct fix |
|
||||
| Tray-triggered diagnostics logging | Pending | Pending | Pending | Pending | Pending | Pending | Use `Run Diagnostics` and confirm the same IDs/messages appear in logs |
|
||||
| Service-failure escalation path | Pending | Pending | Pending | Pending | Pending | Pending | Confirm `doctor` -> `self-check` -> `journalctl` -> `aman run --verbose` is enough to explain the failure |
|
||||
| Service restart after a successful install | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); verify `systemctl --user restart aman` returns to the tray/ready state |
|
||||
| Reboot followed by successful reuse | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); validate recovery after a real session restart |
|
||||
| Offline startup with an already-cached model | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); cached-model offline start succeeded |
|
||||
| Missing runtime dependency recovery | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); diagnostics pointed to the fix |
|
||||
| Tray-triggered diagnostics logging | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); `Run Diagnostics` matched the documented log path |
|
||||
| Service-failure escalation path | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); `doctor` -> `self-check` -> `journalctl` -> `aman run --verbose` was sufficient |
|
||||
|
|
|
|||
36
user-readiness/1773357669.md
Normal file
36
user-readiness/1773357669.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Arch Linux Validation Notes
|
||||
|
||||
- Date: 2026-03-12
|
||||
- Reviewer: User
|
||||
- Environment: Arch Linux on X11
|
||||
- Release candidate: `1.0.0`
|
||||
- Evidence type: user-reported manual validation
|
||||
|
||||
This note records the Arch Linux validation pass used to close milestones 2 and
|
||||
3 for now. It is sufficient for milestone closeout, but it does not replace the
|
||||
full Debian/Ubuntu, Fedora, and openSUSE coverage still required for milestone
|
||||
5 GA signoff.
|
||||
|
||||
## Portable lifecycle
|
||||
|
||||
| Scenario | Result | Notes |
|
||||
| --- | --- | --- |
|
||||
| Fresh install | Pass | Portable bundle install succeeded on Arch X11 |
|
||||
| First service start | Pass | `systemctl --user` service came up successfully |
|
||||
| Upgrade | Pass | Upgrade preserved the existing state |
|
||||
| Uninstall | Pass | Portable uninstall completed cleanly |
|
||||
| Reinstall | Pass | Reinstall succeeded after uninstall |
|
||||
| Reboot or service restart | Pass | Service remained usable after restart |
|
||||
| Missing dependency recovery | Pass | Dependency failure path was recoverable |
|
||||
| Conflict with prior package install | Pass | Conflict handling behaved as documented |
|
||||
|
||||
## Runtime reliability
|
||||
|
||||
| Scenario | Result | Notes |
|
||||
| --- | --- | --- |
|
||||
| Service restart after a successful install | Pass | Service returned to the expected ready state |
|
||||
| Reboot followed by successful reuse | Pass | Aman remained usable after restart |
|
||||
| Offline startup with an already-cached model | Pass | Cached-model startup worked without network access |
|
||||
| Missing runtime dependency recovery | Pass | Diagnostics pointed to the correct recovery path |
|
||||
| Tray-triggered diagnostics logging | Pass | `Run Diagnostics` matched the documented log flow |
|
||||
| Service-failure escalation path | Pass | `doctor` -> `self-check` -> `journalctl` -> `aman run --verbose` was sufficient |
|
||||
Loading…
Add table
Add a link
Reference in a new issue