thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions

Prepare the 1.0.0 GA release surface

Browse source 
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
This commit is contained in:
Thales Maciel 2026-03-12 19:36:52 -03:00
parent acfc376845
commit 31a1e069b3
No known key found for this signature in database
GPG key ID: 33112E6833C34679
28 changed files with 591 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

7
docs/developer-workflows.md
View file

@ -13,14 +13,21 @@ make package-deb
make package-arch
make runtime-check
make release-check
make release-prep
```
- `make package-portable` builds `dist/aman-x11-linux-<version>.tar.gz` plus
its `.sha256` file.
- `make release-prep` runs `make release-check`, builds the packaged artifacts,
and writes `dist/SHA256SUMS` for the release page upload set.
- `make package-deb` installs Python dependencies while creating the package.
- For offline Debian packaging, set `AMAN_WHEELHOUSE_DIR` to a directory
containing the required wheels.
For `1.0.0`, the manual publication target is the forge release page at
`https://git.thaloco.com/thaloco/aman/releases`, using
[`docs/releases/1.0.0.md`](./releases/1.0.0.md) as the release-notes source.
## Developer setup
`uv` workflow:

6
docs/persona-and-distribution.md
View file

@ -36,7 +36,7 @@ Design implications:
The current release channels are:
1. Current canonical end-user channel: portable X11 bundle (`aman-x11-linux-<version>.tar.gz`).
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`.
@ -75,7 +75,7 @@ variant.
## Release and Support Policy
- App versioning follows SemVer (`0.y.z` until API/UX stabilizes).
- 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
@ -86,5 +86,7 @@ variant.
- 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.

8
docs/portable-install.md
View file

@ -5,6 +5,9 @@ This is the canonical end-user install path for Aman on X11.
For the shortest first-run path, screenshots, and the expected tray/dictation
result, start with the quickstart in [`README.md`](../README.md).
Download published bundles, checksums, and release notes from
`https://git.thaloco.com/thaloco/aman/releases`.
## Supported environment
- X11 desktop session
@ -42,7 +45,7 @@ sudo zypper install -y portaudio gtk3 libayatana-appindicator3-1 python3-gobject
## Fresh install
1. Download `aman-x11-linux-<version>.tar.gz` and `aman-x11-linux-<version>.tar.gz.sha256`.
1. Download `aman-x11-linux-<version>.tar.gz` and `aman-x11-linux-<version>.tar.gz.sha256` from the releases page.
2. Verify the checksum.
3. Extract the bundle.
4. Run `install.sh`.
@ -150,3 +153,6 @@ If installation succeeds but runtime behavior is wrong, use the supported recove
The failure IDs and example outputs for this flow are documented in
[`docs/runtime-recovery.md`](./runtime-recovery.md).
Public support and issue reporting instructions live in
[`SUPPORT.md`](../SUPPORT.md).

20
docs/release-checklist.md
View file

@ -5,26 +5,27 @@ GA signoff bar. The GA signoff sections are required for `v1.0.0` and later.
1. Update `CHANGELOG.md` with final release notes.
2. Bump `project.version` in `pyproject.toml`.
3. Run quality and build gates:
- `make release-check`
- `make runtime-check`
- `make check-default-model`
4. Ensure model promotion artifacts are current:
3. Ensure model promotion artifacts are current:
- `benchmarks/results/latest.json` has the latest `winner_recommendation.name`
- `benchmarks/model_artifacts.json` contains that winner with URL + SHA256
- `make sync-default-model` (if constants drifted)
5. Build packaging artifacts:
- `make package`
6. Verify artifacts:
4. Prepare the release candidate:
- `make release-prep`
5. Verify artifacts:
- `dist/*.whl`
- `dist/aman-x11-linux-<version>.tar.gz`
- `dist/aman-x11-linux-<version>.tar.gz.sha256`
- `dist/SHA256SUMS`
- `dist/*.deb`
- `dist/arch/PKGBUILD`
6. Verify checksums:
- `sha256sum -c dist/SHA256SUMS`
7. Tag release:
- `git tag vX.Y.Z`
- `git push origin vX.Y.Z`
8. Publish release and upload package artifacts from `dist/`.
8. Publish `vX.Y.Z` on `https://git.thaloco.com/thaloco/aman/releases` and upload package artifacts from `dist/`.
- Use [`docs/releases/1.0.0.md`](./releases/1.0.0.md) as the release-notes source for the GA release.
- Include `dist/SHA256SUMS` with the uploaded artifacts.
9. Portable bundle release signoff:
- `README.md` points end users to the portable bundle first.
- [`docs/portable-install.md`](./portable-install.md) matches the shipped install, upgrade, uninstall, and purge behavior.
@ -49,3 +50,4 @@ GA signoff bar. The GA signoff sections are required for `v1.0.0` and later.
- The portable installer, upgrade path, and uninstall path are validated.
- End-user docs and release notes match the shipped artifact set.
- Public metadata, checksums, and support/reporting surfaces are complete.
- [`docs/x11-ga/ga-validation-report.md`](./x11-ga/ga-validation-report.md) links the release page, matrices, and raw evidence files.

69
docs/releases/1.0.0.md Normal file
View file

@ -0,0 +1,69 @@
# Aman 1.0.0
This is the first GA-targeted X11 release for Aman.
- Canonical release page:
`https://git.thaloco.com/thaloco/aman/releases/tag/v1.0.0`
- Canonical release index:
`https://git.thaloco.com/thaloco/aman/releases`
- Support and issue reporting:
`thales@thalesmaciel.com`
## Supported environment
- X11 desktop sessions only
- `systemd --user` for supported daily use
- System CPython `3.10`, `3.11`, or `3.12` for the portable installer
- Runtime dependencies installed from the distro package manager
- Representative validation families: Debian/Ubuntu, Arch, Fedora, openSUSE
## Artifacts
The release page should publish:
- `aman-x11-linux-1.0.0.tar.gz`
- `aman-x11-linux-1.0.0.tar.gz.sha256`
- `SHA256SUMS`
- wheel artifact from `dist/*.whl`
- Debian package from `dist/*.deb`
- Arch package inputs from `dist/arch/PKGBUILD` and `dist/arch/*.tar.gz`
## Install, update, and uninstall
- Install: download the portable bundle and checksum from the release page,
verify the checksum, extract the bundle, then run `./install.sh`
- Update: extract the newer bundle and run its `./install.sh`
- Uninstall: run `~/.local/share/aman/current/uninstall.sh`
- Purge uninstall: run `~/.local/share/aman/current/uninstall.sh --purge`
The full end-user lifecycle is documented in
[`docs/portable-install.md`](../portable-install.md).
## Recovery path
If the supported path fails, use:
1. `aman doctor --config ~/.config/aman/config.json`
2. `aman self-check --config ~/.config/aman/config.json`
3. `journalctl --user -u aman`
4. `aman run --config ~/.config/aman/config.json --verbose`
Reference diagnostics and failure IDs live in
[`docs/runtime-recovery.md`](../runtime-recovery.md).
## Support
Email `thales@thalesmaciel.com` with:
- distro and version
- X11 confirmation
- install channel and Aman version
- `aman doctor` output
- `aman self-check` output
- relevant `journalctl --user -u aman` lines
## Non-goals
- Wayland support
- Flatpak or snap as the canonical GA path
- Native-package parity across every Linux distro

1
docs/x11-ga/05-ga-candidate-validation-and-release.md
View file

@ -58,3 +58,4 @@ The final step to GA is not more feature work. It is proving that Aman has a rea
- 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.
- Raw validation evidence stored in `user-readiness/<linux-timestamp>.md` and linked from the validation matrices.

7
docs/x11-ga/README.md
View file

@ -106,7 +106,12 @@ Any future docs, tray copy, and release notes should point users to this same se
[`first-run-review-notes.md`](./first-run-review-notes.md) plus
[`user-readiness/1773352170.md`](../../user-readiness/1773352170.md).
- [ ] [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.
Implementation landed on 2026-03-12: repo metadata now uses the real
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.
## Cross-milestone acceptance scenarios

54
docs/x11-ga/ga-validation-report.md Normal file
View file

@ -0,0 +1,54 @@
# GA Validation Report
This document is the final rollup for the X11 GA release. It does not replace
the underlying evidence sources. It links them and records the final signoff
state.
## Where to put validation evidence
- Put raw manual validation notes in `user-readiness/<linux-timestamp>.md`.
- Use one timestamped file per validation session, distro pass, or reviewer
handoff.
- In the raw evidence file, record:
- distro and version
- reviewer
- date
- release artifact version
- commands run
- pass/fail results
- failure details and recovery outcome
- 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)
## Release metadata
- Release version: `1.0.0`
- Release page:
`https://git.thaloco.com/thaloco/aman/releases/tag/v1.0.0`
- Support channel: `thales@thalesmaciel.com`
- License: MIT
## Evidence sources
- Portable lifecycle matrix:
[`portable-validation-matrix.md`](./portable-validation-matrix.md)
- Runtime reliability matrix:
[`runtime-validation-report.md`](./runtime-validation-report.md)
- First-run review:
[`first-run-review-notes.md`](./first-run-review-notes.md)
- Raw evidence archive:
[`user-readiness/README.md`](../../user-readiness/README.md)
- Release notes:
[`docs/releases/1.0.0.md`](../releases/1.0.0.md)
## Final signoff status
| 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 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` |
| Published release page | Pending | Publish `v1.0.0` on the forge release page and attach the prepared artifacts |

3
docs/x11-ga/portable-validation-matrix.md
View file

@ -20,6 +20,9 @@ Completed on 2026-03-12:
These rows must be filled with real results before milestone 2 can be closed as
fully complete for GA evidence.
Store raw evidence for each distro pass in `user-readiness/<linux-timestamp>.md`
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 | |

4
docs/x11-ga/runtime-validation-report.md
View file

@ -34,6 +34,10 @@ Completed on 2026-03-12:
These rows must be filled with release-specific evidence before milestone 3 can
be closed as complete for GA signoff.
Store raw evidence for each runtime validation pass in
`user-readiness/<linux-timestamp>.md` and reference that file in the `Notes`
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 |