From 43b2b44782e2789b9068b27dcac73926660d07a8 Mon Sep 17 00:00:00 2001 From: lozenge0 <7510861+lozenge0@users.noreply.github.com> Date: Sun, 13 Sep 2026 10:52:13 +0100 Subject: [PATCH] Reorganize docs, rewrite changelog and add existing-install guidance - Move the seven dated experiment reports to docs/reports/ and fold PLAN.md and PUBLISHING.md into MAINTAINER.md. - Rewrite CHANGELOG.md in Keep a Changelog form with user-facing entries only. - Keep the file inventory in tests/test_publication.py alone and drop the copy in the release review. - Replace sentence assertions in tests with heading, link and token checks. - Add an "Already installed?" README section for the icon and port changes, linked from the configuration reference. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Nrm65fBRmGmRBTW3PhyeMm --- CHANGELOG.md | 89 +++++------ CONTRIBUTING.md | 10 +- README.md | 15 ++ docs/CONFIGURATION.md | 2 + docs/MAINTAINER.md | 148 ++++++++++++------ docs/PLAN.md | 99 ------------ docs/PUBLISHING.md | 81 ---------- docs/RELEASE-REVIEW.md | 56 ++----- docs/VALIDATION.md | 14 +- docs/{ => reports}/CPU-RETEST-20260912.md | 0 docs/{ => reports}/FIRST-RUN-FINDINGS.md | 0 docs/{ => reports}/RECREATION-TEST.md | 0 .../{ => reports}/SHORT-TEXT-INVESTIGATION.md | 0 docs/{ => reports}/UI-TEST-PREFLIGHT.md | 0 docs/{ => reports}/UPDATE-ROLLBACK-TEST.md | 0 docs/{ => reports}/USER-IDENTITY-TESTS.md | 0 tests/test_publication.py | 33 ++-- tests/test_template.py | 1 - 18 files changed, 196 insertions(+), 352 deletions(-) delete mode 100644 docs/PLAN.md delete mode 100644 docs/PUBLISHING.md rename docs/{ => reports}/CPU-RETEST-20260912.md (100%) rename docs/{ => reports}/FIRST-RUN-FINDINGS.md (100%) rename docs/{ => reports}/RECREATION-TEST.md (100%) rename docs/{ => reports}/SHORT-TEXT-INVESTIGATION.md (100%) rename docs/{ => reports}/UI-TEST-PREFLIGHT.md (100%) rename docs/{ => reports}/UPDATE-ROLLBACK-TEST.md (100%) rename docs/{ => reports}/USER-IDENTITY-TESTS.md (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 283bc40..9041f45 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,54 +1,39 @@ # Changelog -## Unreleased — targeting v0.1.0 - -- Added a `Changes` field to the template so Community Apps shows a changelog - to users who already installed the app. -- Project status now lives in one place, the top of `docs/RELEASE-REVIEW.md`. - Other documents link to it. Removed internal review narrative and stale test - and file counts from the public documentation. -- The publication inventory test now reads Git's file list, so `pytest` caches - and other ignored files no longer fail it. Tests check document structure and - links rather than exact status sentences. -- Added a PNG export of the existing community artwork and switched template/profile - icon URLs to PNG for Docker Manager compatibility. Original SVG preserved. -- Changed the default host WebUI/API port to `6969` for CPU, CUDA 12 and CUDA 13 - installations. Internal port `8080` and WebUI port resolution remain unchanged; - existing installations retain their configured host port. -- Reworked the README around first-time use, hardware choice, installation and a - first speech sample. Moved detailed configuration, validation context and - maintainer notes into linked guides without changing container settings. -- Added AI alongside Tools categorization for the base app and inherited CUDA - variants. Replaced pre-submission wording after owner-reported CA auto-approval; - beta status, catalog visibility uncertainty and remaining runtime checks retained. -- Initial draft: one Community Apps template with CPU, CUDA 12 and CUDA 13 variants. -- Direct moving upstream image references; no application builds or runtime wrappers. -- Native model storage, network port and NVIDIA selection fields. -- Native Docker `--user=99:100` for all variants, matching tested Unraid-created - model-directory ownership without modifying upstream images or file permissions. -- Isolated CPU/CUDA 12/CUDA 13 downloads and browser/API inference, plus - owner-operated installation of pre-expanded private CA templates. -- Controlled CUDA 13 recreation, newer-image update and retained-container - rollback with configuration/model integrity checks. -- September 12 fixed official CPU image passed short-text, explicit streaming - and restart regression tests; owner subsequently confirmed playback. -- Public CA branch selection, full DockerMan/scheduled update workflows and - optional JSON configuration remain outstanding; no full acceptance claim. -- Reconciled release review and explicit publication file list. -- Upstream artwork-independent community icon supplied by the project owner. -- Owner approved MIT for integration files and CC0 1.0 for the icon on September - 12, limited to rights they hold; upstream licences are unchanged. -- Local structural checks and a deployment acceptance checklist. -- Independent pre-GitHub template/privacy review; removed a host-specific GPU - prefix from a test fixture, clarified optional JSON validation and image ID labels. -- Local light/dark icon previews and read-only embedded metadata inspection; - original artwork unchanged. -- Prepared least-privilege, commit-pinned GitHub Actions CI, Dependabot action - updates, contribution/security guidance and a standalone Git publishing checklist. -- September 13: published the approved GitHub review draft with a clean signed - history and noreply commit identity. First hosted CI passed. Public links, - file hashes and recorded repository security settings verified. - -No public versioned release has been made; the GitHub repository is a review draft. -Version numbers describe the Unraid integration, -not upstream audio.cpp. v1.0.0 is reserved for a validated stable integration. +User-facing changes to the Unraid integration. The format follows +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version numbers +describe this integration, not upstream audio.cpp. `v1.0.0` is reserved for a +validated stable integration. Entries that affect installed users are mirrored +in the template's `Changes` field, which Community Apps shows as the app changelog. + +## [Unreleased] + +Targeting `v0.1.0`, the first beta release. + +### Added + +- Community Apps template for audio.cpp with CPU, NVIDIA CUDA 12 and NVIDIA + CUDA 13 variants, using unmodified upstream Docker images. +- Model storage, host port and NVIDIA GPU selection fields. +- A `Changes` field in the template so Community Apps shows release notes. +- A PNG export of the community icon for the Unraid Docker page. +- First-time user guide in the README, with configuration, maintainer and + validation notes under `docs/`. + +### Changed + +- New installations default to host port `6969`. Existing installations keep + their configured port. +- Every variant runs as Docker user `99:100`, which matches the ownership of + model folders that Unraid creates. No image or file permissions are changed. + +### Fixed + +- The Unraid Docker page showed no icon because the template pointed at an SVG. + Docker Manager caches icons as PNG. + +### Known limitations + +- Public Community Apps branch selection, scheduled container updates and the + optional JSON configuration path are not yet validated. See the + [release review](docs/RELEASE-REVIEW.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e11d417..1e13907 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,10 +16,12 @@ Before proposing a change: 1. Explain its purpose and keep changes scoped to the integration. 2. Run `python3 -m unittest discover -s tests -v` from the repository root. -3. If adding a file, review its publication safety and update both the explicit - inventory in `tests/test_publication.py` and [release review](docs/RELEASE-REVIEW.md). -4. Update setup guidance and the changelog when behavior changes. Record runtime - tests separately from local structural tests; CI has no Unraid server or GPU. +3. If adding a file, review its publication safety and add it to the explicit + inventory in `tests/test_publication.py`. +4. If behavior changes, update setup guidance and the changelog. If the change + affects installed users, add an entry to the template's `Changes` field. + Record runtime tests in a dated report under `docs/reports/`. CI has no + Unraid server or GPU. Pull requests run read-only CI on GitHub-hosted runners. Passing CI does not prove hardware compatibility or CA acceptance. Action updates are proposed by Dependabot diff --git a/README.md b/README.md index 2b0aa53..48c4df6 100644 --- a/README.md +++ b/README.md @@ -134,6 +134,21 @@ See [permissions](docs/CONFIGURATION.md#storage-permissions-and-process-identity and [updates/rollback](docs/CONFIGURATION.md#updates-persistence-and-rollback) for the details. +## Already installed? + +Unraid does not update the template of a container that is already installed. +Changes to this template apply to new installations only. The app's change log +in the Apps tab lists each change. If you installed before 2026-09-13: + +- The default host port changed to `6969` for new installations. Your + container keeps its current port. Nothing to do. +- The app icon changed to a PNG so that the Docker page can show it. To get + the new icon, remove the container (your model folder stays), then install + `audio-cpp` again from the Apps tab with the same port and folder. If the old + icon still shows, Unraid kept a cached copy at + `/boot/config/plugins/dockerMan/images/audio-cpp-icon.png`. Delete that file + and reload the Docker page. + ## Need help? - **WebUI will not open:** check that the container is running, its logs, and the diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index e830b59..5305cbf 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -162,6 +162,8 @@ container is recreated. We run no image-building or image-mirroring pipeline. Updates remain on the selected CPU/CUDA tag; they do not switch backend, upgrade host drivers, update model weights, or safely migrate every installation setting. Template changes are not a universal migration mechanism for installed containers. +The README section [Already installed?](../README.md#already-installed) lists +the template changes that an existing installation can adopt by hand. An existing installation is not automatically migrated to UID `99` / GID `100` by this template change. Review its current identity and storage before adopting the setting; preserve the matching identity throughout an image update/rollback. diff --git a/docs/MAINTAINER.md b/docs/MAINTAINER.md index fd04399..f38067f 100644 --- a/docs/MAINTAINER.md +++ b/docs/MAINTAINER.md @@ -1,77 +1,135 @@ # Maintainer guide For installation and everyday use, start with the [README](../README.md). -This page collects project scope, validation history, release process and sources -previously in the README. The [release review](RELEASE-REVIEW.md) is the current -status tracker; detailed experiment reports remain in this docs directory. +This page holds project scope, fixed decisions, the release process and the +maintainer checks. [The release review](RELEASE-REVIEW.md) is the status +tracker. Dated experiment reports live in `docs/reports/`. -## Validation and submission context +## Status and evidence The current submission state, completed evidence and remaining gates live in [the release review](RELEASE-REVIEW.md). Do not repeat that status here. -CPU, CUDA 12 and CUDA 13 passed isolated Pocket TTS testing on one -Unraid host. Native Docker `--user=99:100` resolved the initial model-folder -permission failure. The [September 12 CPU retest](CPU-RETEST-20260912.md) passed +CPU, CUDA 12 and CUDA 13 passed isolated Pocket TTS testing on one Unraid host. +Native Docker `--user=99:100` resolved the initial model-folder permission +failure. The [September 12 CPU retest](reports/CPU-RETEST-20260912.md) passed short-text, streaming and restart checks on a fixed official image. Controlled CUDA 13 recreation, image update and rollback passed within their documented scope. These are not full Community Apps release acceptance, and portal approval does not establish runtime compatibility. -The repository is `lozenge0/audio-cpp-unraid`, with GitHub Issues for support. -The template requests both **AI** and **Tools** categories. +## Decisions fixed by the project owner + +- Project: audio.cpp for Unraid. Repository: `lozenge0/audio-cpp-unraid`. + Support: repository GitHub Issues. +- Template: CPU base with CUDA 12 and CUDA 13 branches, all on unmodified + upstream images and moving upstream tags. No custom image, fork, runtime + wrapper, personal code or configuration. +- Every variant runs as Docker `--user=99:100`. No ownership-changing helper + and no `PUID`/`PGID` mapping. +- Standard Unraid controls only, plus optional upstream CLI arguments or a + user-owned JSON file. +- Licences: MIT for integration files and CC0 1.0 for the icon, approved on + 2026-09-12. The artwork dedication covers only the rights the owner holds. + The owner confirmed the artwork came from their own prompts with Claude/AI. +- Versions: `v0.1.0` is the first beta release. `v1.0.0` is reserved for a + validated stable integration. Integration versions do not describe the + upstream audio.cpp version inside the container. +- Upstream now builds a Vulkan image. A Vulkan branch needs its own integration + and hardware review before it is added. ## Scope and layout This is a standalone integration repository with its own clean Git history. -It was prepared separately from the upstream audio.cpp source; no upstream -checkout/history belongs here. Do not build an application image from this +It was prepared separately from the upstream audio.cpp source. No upstream +checkout or history belongs here. Do not build an application image from this repository. Nothing here changes an existing personal installation. - `templates/audio-cpp.xml`: one app with CPU base and two CUDA branches. - `ca_profile.xml`: Community Apps repository metadata. -- `assets/`: supplied community integration icon and provenance/licensing notes. -- `docs/PLAN.md`: implementation stages and approval boundaries. +- `assets/`: community integration icon and provenance/licensing notes. +- `docs/CONFIGURATION.md`: detailed deployment and tuning notes. +- `docs/RELEASE-REVIEW.md`: current status, evidence and remaining gates. - `docs/VALIDATION.md`: acceptance checklist and evidence requirements. -- `docs/RELEASE-REVIEW.md`: current release status and publication boundaries. -- [Configuration reference](CONFIGURATION.md): detailed deployment and tuning notes. -- `tests/`: maintainer-only structural checks; never shipped into the container. +- `docs/reports/`: dated experiment reports. They record what was known at + the time and are not updated later. +- `tests/`: maintainer-only structural checks, never shipped into the container. - `.github/`: read-only CI checks and Dependabot updates for the CI actions only. -The project is called **audio.cpp for Unraid**; the template/container name is -`audio-cpp`. Integration versions (`v0.1.0`, eventually `v1.0.0`) do not represent -the version of upstream audio.cpp running inside the container. This integration -does not imply endorsement by the audio.cpp maintainers or Unraid. +The project is called **audio.cpp for Unraid**. The template and container name +is `audio-cpp`. This integration does not imply endorsement by the audio.cpp +maintainers or Unraid. -## Maintainer checks and publishing +## Maintainer checks -Run from the repository root (not this docs directory), with Python 3.9+: +Run from the repository root, with Python 3.9 or later: ```sh python3 -m unittest discover -s tests -v ``` -These checks validate local structural/design invariants, not the CA parser, -live registry availability, hardware, browser workflows, or installation success. -Follow [the release review](RELEASE-REVIEW.md) and -[full acceptance checklist](VALIDATION.md) before any release. +These checks validate local structural invariants, not the CA parser, live +registry availability, hardware, browser workflows or installation success. +The publication test holds the exact list of files that belong in the +repository. If you add a file, review its publication safety first, then add +it to that list. + +GitHub Actions runs the same tests on pushes, pull requests and manual +dispatch. The workflow uses GitHub-hosted Ubuntu, a read-only repository token, +commit-pinned official actions and no persisted checkout credentials. There are +no application builds, deployments, artifact uploads, scheduled server tasks, +custom secrets or access to Unraid. Do not add an Unraid SSH key or API token to +repository secrets. Dependabot proposes weekly updates for the CI actions only. +It does not track audio.cpp releases or merge its own pull requests. + +Keep these repository settings: + +- Default branch `main` is protected by the validation status check. Force + pushes and deletion are blocked. +- Issues are enabled. Auto-merge is disabled. +- The Actions token is read-only, Actions cannot approve pull requests, and + workflows from outside contributors need approval. +- Private vulnerability reporting, secret scanning and push protection are on. -The GitHub Actions workflow runs these tests on pushes, pull requests -and manual dispatch, with no custom secrets, image builds or server access. -Dependabot proposes CI action updates for review, not container updates. See [contribution guidance](../CONTRIBUTING.md) and [security reporting](../SECURITY.md). -Next verify catalog visibility and the public branch-selection/install flow, -review tested images and complete or explicitly defer outstanding lifecycle -checks. Rerun CA Validate/Scan after meaningful XML changes. Follow the -[GitHub publishing checklist](PUBLISHING.md). Never publish the surrounding -audio.cpp checkout. Portal approval is not full deployment acceptance. - -When a template change affects installed users, add a dated entry to the -`Changes` field in `templates/audio-cpp.xml`. Community Apps shows that field -as the app changelog. Docker Manager does not refresh installed templates, so -the entry must say what an existing user needs to change by hand. +## Release process + +1. Run the maintainer checks. For a template change, also run CA Validate/Scan + against the public repository and resolve findings. +2. If a change affects installed users, add a dated entry to the `Changes` + field in `templates/audio-cpp.xml`. Community Apps shows that field as the app + changelog. Docker Manager does not refresh installed templates, so the entry + must say what an existing user needs to change by hand. Mirror the entry in + `CHANGELOG.md`. +3. Update the [release review](RELEASE-REVIEW.md) status section and, for + runtime changes, the [validation checklist](VALIDATION.md). Record runtime + tests in a dated report under `docs/reports/`. CI has no Unraid server or GPU. +4. Open a pull request and merge it after CI passes. +5. Once the app is visible in the public catalog and the open release gates are + complete or explicitly deferred, tag `v0.1.0` and create a GitHub release + from the changelog. + +Never publish the surrounding audio.cpp checkout. If the repository is ever +restaged, start from a new directory and make sure that +`git rev-parse --show-toplevel` points at it. Copy only the files in the +publication list. Use the GitHub noreply commit identity and a fresh root +commit. Never force-push. + +## Ongoing maintenance + +Upstream images update independently. Monitor changes to launch arguments, +permissions, storage, driver requirements and security. If one of them +changes, update the template and docs. Changes that affect existing +installations need explicit migration instructions in the README and in the +`Changes` field. No remote access to other users' servers is required. +Release-only image tags are a separate upstream request. + +Testing on the owner's server follows fixed rules. Use a separate container +name, an unused port and a fresh appdata directory. Never replace the personal +container. Never run a host-wide updater to test one container. Make sure that +free disk space is enough before you pull more CUDA images. ## Primary references @@ -84,12 +142,12 @@ the entry must say what an existing user needs to change by hand. - [Unraid container settings](https://docs.unraid.net/unraid-os/using-unraid-to/run-docker-containers/managing-and-customizing-containers/) - [NVIDIA container GPU selection](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html) - [CUDA 13 compatibility changes](https://docs.nvidia.com/cuda/archive/13.0.0/cuda-toolkit-release-notes/index.html) +- [GitHub workflow security guidance](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions) ## Licensing -The [MIT licence](../LICENSE) applies to this integration's templates, documentation -and tests, not upstream software, third-party dependencies or model weights. -The icon is separately dedicated under CC0 1.0 Universal, to the extent the owner -holds applicable rights; see [artwork provenance and terms](../assets/README.md). -The owner approved these choices and subsequent GitHub draft publication on -2026-09-12. +The [MIT licence](../LICENSE) applies to this integration's templates, +documentation and tests, not to upstream software, third-party dependencies or +model weights. The icon is separately dedicated under CC0 1.0 Universal, to the +extent the owner holds applicable rights. See +[artwork provenance and terms](../assets/README.md). diff --git a/docs/PLAN.md b/docs/PLAN.md deleted file mode 100644 index 3c5146c..0000000 --- a/docs/PLAN.md +++ /dev/null @@ -1,99 +0,0 @@ -# Implementation plan - -## Decisions fixed by the project owner - -- Project: audio.cpp for Unraid; standalone repository: audio-cpp-unraid. -- GitHub owner: lozenge0; integration support: repository GitHub Issues. -- Artwork provenance: owner confirms original Claude/AI generation from their - own prompts. MIT for integration files and CC0 for the icon approved 2026-09-12, - with the artwork dedication limited to whatever rights the owner holds. -- No personal code/configuration, upstream fork, custom image or runtime wrapper. -- Current template: CPU base, CUDA 12 and CUDA 13 branches. Upstream now has a - Vulkan Docker build; adding a branch awaits separate integration/hardware review. -- Follow moving upstream Docker tags. No independent image release pipeline. -- Standard Unraid controls plus optional upstream CLI/user-owned JSON. -- Native Docker `--user=99:100` in every variant, following successful isolated - download/inference tests; no ownership-changing helper or `PUID`/`PGID` mapping. -- Draft first release v0.1.0; stable integration v1.0.0 after validation. - -## Current publication status - -See the status section at the top of [the release review](RELEASE-REVIEW.md). -That file is the single source for submission state, evidence and remaining -checks. No production migration took place. - -## Runtime progress recorded on 2026-09-12 - -The local template now includes the successfully tested Docker user/group setting. -Isolated CPU/CUDA 12/CUDA 13 downloads and browser/API inference passed; CPU/CUDA 13 -restart and CUDA 12 recreation checks passed. See USER-IDENTITY-TESTS.md for the -tested images and limits. Subsequent pre-expanded private CA UI tests, controlled -CUDA 13 recreation/update/rollback, and the fixed official CPU short-text/streaming -retest have passed within their documented scopes. See VALIDATION.md and -CPU-RETEST-20260912.md. The public branch selector, scheduled updater and remaining -release checklist are still pending. No publication or migration of the existing -personal deployment has taken place. -The owner confirmed successful playback on the fixed CPU image. The reconciled -status, publication file list and remaining decisions are in RELEASE-REVIEW.md. -Read-only UI preflight found two prerequisites: owner browser authentication and -a supported feed/preview route for the branch picker. Installed CA private apps -can test pre-expanded variants but not the selector. See UI-TEST-PREFLIGHT.md. - -## Stage 1 — local preparation - -Prepare standalone metadata, template, supplied icon, documentation and local -structural tests. Independently review the template and preserve the current -personal deployment. No Git repository has been created or published by this step. -Review completion is recorded separately from live deployment acceptance. - -## Stage 2 — isolated validation (partially complete) - -Agree on a separate test-container name, unused port and fresh dedicated appdata -directory; never inherit production paths or replace the existing audio-cpp -container. Check available disk space before pulling more CUDA images. Run the -checklist in VALIDATION.md, including real CA branch expansion/DockerMan rendering, -empty-directory permissions, browser downloads, CPU and both CUDA inference, -model/config persistence, and image update/rollback. Use safe test workloads -compatible with the other GPU users. Record exact images/models and results. - -The initial fresh-directory permission failure was resolved in isolated tests -using Docker `--user=99:100`; the local draft now includes it in all variants. -Public branch selection, full DockerMan/scheduled updates and broader compatibility -checks remain; controlled CUDA 13 update/rollback is already recorded as passing. -If a storage layout or future image fails, review it before changing identity -or permissions. Do not silently add root execution, recursive broad ownership -changes, or startup helpers. CPU/CUDA13 cannot be advertised as tested merely -because the earlier personal CUDA12 service works. - -## Stage 3 — publication identity and beta - -GitHub publication, support URLs, CI and MIT/CC0 terms are recorded. The owner -reviewed the repository and subsequently submitted it to CA. Follow PUBLISHING.md -for the repository setup record. Confirm app/container naming and category in -the public listing. Local SVG checks at 32/48/180 px on light/dark backgrounds -passed; actual CA rendering and full deployment acceptance remain pending. - -## Stage 4 — Community Apps submission - -Confirm catalog visibility and review Validate/Scan results. Rerun those checks -after meaningful XML changes. Do not -create a duplicate submission because the listing is not yet visible. Preserve -tested-combination limits, maintenance/support boundaries and rollback guidance. - -## Ongoing maintenance - -Upstream images update independently. Monitor changes to launch arguments, -permissions, storage, driver requirements and security; update template/docs when -needed. Changes that affect existing installs need explicit migration instructions. -No remote access to other users' servers is required. Release-only image tags -would be a separate upstream request if desired. Vulkan integration is a separate -review of the now-existing upstream build, not a reason to build our own image. - -## Approval boundaries - -Local draft preparation and local tests are in scope now. Deploying test containers, -altering the live service, creating/pushing a public GitHub repository, contacting -upstream, submitting to CA, or granting publication rights are separate decisions. -The owner approved the isolated baseline/user-identity experiments already -recorded, followed by local template adoption and review. Those approvals do not -authorize production migration, publication or changes to global updater settings. diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md deleted file mode 100644 index 360ddf5..0000000 --- a/docs/PUBLISHING.md +++ /dev/null @@ -1,81 +0,0 @@ -# GitHub preparation and publication - -The intended destination is `lozenge0/audio-cpp-unraid`, with default branch -`main` and GitHub Issues for support. The owner wants to review the draft on -GitHub. Publishing that draft is separate from approving a beta release or -submitting to Community Apps. The owner explicitly approved standalone Git -initialization and public draft creation/push on 2026-09-12. This is not approval -for a release tag or CA submission. See RELEASE-REVIEW.md for completed operations. - -## Clean standalone Git history - -The original candidate was prepared inside another checkout. Publication uses -a separate sibling directory and a fresh root commit, with no parent Git history. -For any future restaging, verify the Git root before staging or changing remotes. - -Approved initialization procedure: - -1. Prefer a new standalone directory outside the upstream checkout. Copy only - files in the [reviewed inventory](RELEASE-REVIEW.md#exact-proposed-file-list), - including `.github` and `.gitignore`; do not copy the parent `.git`, history, - ignored files, original artwork pack or private test artifacts. -2. Initialize that directory with `git init -b main`. Verify - `git rev-parse --show-toplevel` identifies the new integration directory. -3. Set repository-local author name and email before the first commit. Prefer - the exact GitHub-provided noreply address from account email settings; do not - guess its format or inherit a personal email without approval. Do not change - global Git settings. Review [GitHub's commit-email guidance](https://docs.github.com/en/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address). -4. Run the tests, inspect the file inventory and stage only reviewed files. Review - `git diff --cached --stat` and `git diff --cached` before the initial commit. - Use a new root commit, not imported upstream history. -5. Verify GitHub authentication as `lozenge0` without printing tokens. Create an - empty repository at the agreed destination and visibility after approval; - do not overwrite an existing repository or auto-add competing licence/README - files. Verify the remote before pushing `main`. Do not force-push. - -The draft was published on September 13 (Europe/London). Publication checks and -the current project status are recorded in [the release review](RELEASE-REVIEW.md). -Keep the beta label and outstanding validation limits visible. - -## CI and repository settings - -The prepared workflow runs stdlib Python tests on pushes to `main`, pull requests -and manual dispatch. It uses GitHub-hosted Ubuntu, a read-only repository token, -commit-pinned official actions and no persisted checkout credentials. There are -no application builds, deployments, artifact uploads, scheduled server tasks, -custom secrets or access to Unraid. GitHub provides the ordinary workflow token; -do not add an Unraid SSH key or API token to repository secrets. - -Dependabot proposes weekly GitHub Actions dependency updates. It does not track -audio.cpp releases, publish images or merge its own pull requests. Container -updates remain driven by the official upstream tags and each user's Unraid -updater. See [GitHub's workflow security guidance](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions). - -After creation, verify rather than assume these settings: - -- Default branch `main`; Issues enabled; Actions enabled with read-only default - token permissions and no permission for Actions to create/approve pull requests. -- Dependabot updates enabled and no auto-merge configured. Review action-pin PRs. -- Require approval for workflows from outside contributors according to the - repository's Actions settings; never use a self-hosted Unraid runner for PRs. -- Enable private vulnerability reporting and verify the reporting option. See - [GitHub's setup guidance](https://docs.github.com/en/code-security/how-tos/report-and-fix-vulnerabilities/configure-vulnerability-reporting/configure-for-a-repository). -- Verify the first CI run on GitHub; local tests do not establish hosted success. - Then protect `main` with the observed validation status check and block force - pushes/deletion where available. A single maintainer need not require an - impossible approval of their own PR; outside contributions should be reviewed. -- Verify README, Issues, template, profile and raw icon URLs. Check the icon in - the real CA/Unraid UI as well as local previews. Enable available secret alerts - and push protection as defense in depth, not a replacement for file review. - -The workflow tests design invariants and publication hygiene, not the full CA -schema, container inference, GPU compatibility or live external links. - -## Later Community Apps release - -Complete or explicitly narrow the remaining [release gates](RELEASE-REVIEW.md), -including actual branch-selection/installation checks, tested image disclosure, -and the relevant lifecycle/configuration tests. Run CA Validate/Scan against the -public repository, resolve findings, obtain owner approval of the reviewed files -and test results, and obtain explicit CA submission approval. Draft repository -publication is not an announcement that these checks passed. diff --git a/docs/RELEASE-REVIEW.md b/docs/RELEASE-REVIEW.md index 80a7d49..c1395ab 100644 --- a/docs/RELEASE-REVIEW.md +++ b/docs/RELEASE-REVIEW.md @@ -37,13 +37,13 @@ Dated test reports in this folder preserve what was known during each experiment | Area | Supported conclusion | Evidence | | --- | --- | --- | | Template | Three complete configurations. Upstream-only launch and native identity controls | `tests/test_template.py` | -| Fresh storage | Native downloads work as 99:100 without ownership-changing helpers | [Identity tests](USER-IDENTITY-TESTS.md) | +| Fresh storage | Native downloads work as 99:100 without ownership-changing helpers | [Identity tests](reports/USER-IDENTITY-TESTS.md) | | Private CA install | Owner installed pre-expanded CPU/CUDA 12/CUDA 13 entries, not the public selector | [UI evidence](VALIDATION.md) | -| CPU regression | Fixed revision `5bea9c7` passes short/long offline, Studio, streaming and restart tests. Owner playback confirmed | [CPU retest](CPU-RETEST-20260912.md) | +| CPU regression | Fixed revision `5bea9c7` passes short/long offline, Studio, streaming and restart tests. Owner playback confirmed | [CPU retest](reports/CPU-RETEST-20260912.md) | | CUDA inference | Both variants initialized/computed with CUDA and passed API/Studio tests | [Validation](VALIDATION.md) | -| Restart/model reuse | Files persist. Some clients must re-register models after a restart | [Identity tests](USER-IDENTITY-TESTS.md) | -| Same-image recreation | Controlled CUDA 13 recreation preserves settings and model data | [Recreation](RECREATION-TEST.md) | -| Update/rollback | Controlled CUDA 13 upgrade and restoration of retained old container passed. Not the full DockerMan/scheduler path | [Update/rollback](UPDATE-ROLLBACK-TEST.md) | +| Restart/model reuse | Files persist. Some clients must re-register models after a restart | [Identity tests](reports/USER-IDENTITY-TESTS.md) | +| Same-image recreation | Controlled CUDA 13 recreation preserves settings and model data | [Recreation](reports/RECREATION-TEST.md) | +| Update/rollback | Controlled CUDA 13 upgrade and restoration of retained old container passed. Not the full DockerMan/scheduler path | [Update/rollback](reports/UPDATE-ROLLBACK-TEST.md) | The old CPU image's `hello` crash remains a historical failure. The owner confirmed the fixed test was "working well" after automated checks. This is listening @@ -95,47 +95,17 @@ The sequence follows [CA submission guidance](https://ca.unraid.net/submit/help) public active repository, OSI-approved root licence, profile/template metadata, then Validate/Scan. -## Exact proposed file list - -Only these relative paths belong in the repository. The publication tests -enforce this list from Git's file inventory, so ignored caches do not count. - -```text -.github/dependabot.yml -.github/workflows/validate.yml -.gitignore -CHANGELOG.md -CONTRIBUTING.md -LICENSE -README.md -SECURITY.md -assets/README.md -assets/icon.png -assets/icon.svg -ca_profile.xml -docs/CONFIGURATION.md -docs/CPU-RETEST-20260912.md -docs/FIRST-RUN-FINDINGS.md -docs/MAINTAINER.md -docs/PLAN.md -docs/PUBLISHING.md -docs/RECREATION-TEST.md -docs/RELEASE-REVIEW.md -docs/SHORT-TEXT-INVESTIGATION.md -docs/UI-TEST-PREFLIGHT.md -docs/UPDATE-ROLLBACK-TEST.md -docs/USER-IDENTITY-TESTS.md -docs/VALIDATION.md -templates/audio-cpp.xml -tests/test_ci.py -tests/test_publication.py -tests/test_template.py -``` +## Repository contents + +The publication test in `tests/test_publication.py` holds the exact list of +files that belong in the repository and compares it with Git's file inventory. +Add a new file to that list only after a publication-safety review. Never include the parent checkout/history, `speak.sh`, `.devops/unraid`, SSH/API credentials, test harnesses, raw Docker inspections, WAVs/screenshots, downloaded -models, personal configuration or original icon pack. Reports here contain selected -technical evidence. Raw artifacts stay outside this folder. +models, personal configuration or original icon pack. Reports under +`docs/reports/` contain selected technical evidence. Raw artifacts stay outside +the repository. ## Local review procedure diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md index 2b6703b..81c251b 100644 --- a/docs/VALIDATION.md +++ b/docs/VALIDATION.md @@ -34,7 +34,7 @@ or server changes were made during this documentation reconciliation. Today's official `full-cpu` image, pinned at revision `5bea9c7`, passed repeated `hello` and longer speech in offline API, native Studio and explicit model-streaming tests, including a fresh-process repeat. Model hashes/permissions and all saved -Unraid configurations were preserved. See [CPU retest results](CPU-RETEST-20260912.md). +Unraid configurations were preserved. See [CPU retest results](reports/CPU-RETEST-20260912.md). The specific short-text crash gate is cleared for this tested image/model/host; full release acceptance is not implied. Current Studio offers Alba for Pocket TTS; the former male demo voice passed API/streaming tests separately. @@ -46,7 +46,7 @@ was stopped and retained to free that port; the personal container remains untou The independently reviewed isolated image update and retained-container rollback passed short/long API speech, Studio generation, CUDA computation, configuration -and model-data checks. See [full results](UPDATE-ROLLBACK-TEST.md). The original +and model-data checks. See [full results](reports/UPDATE-ROLLBACK-TEST.md). The original pinned CUDA 13 test was restored and running at that test's completion; it was later stopped for the September 12 CPU retest. This is not CA scheduled-updater or full DockerMan-update acceptance. @@ -116,7 +116,7 @@ The owner subsequently reported a successful restart and model reuse without redownloading. Inspection before the recreation phase confirmed the new process start and retained settings. The separately approved same-image recreation also passed API/browser inference and integrity checks; see -[recreation results](RECREATION-TEST.md). Distinct-image updates, rollback and +[recreation results](reports/RECREATION-TEST.md). Distinct-image updates, rollback and JSON persistence remain separate acceptance gates. ### CPU failure and follow-up @@ -149,15 +149,15 @@ found the official CPU image at revision `05f9c5d`, including the fix, with dige `sha256:370e71fc53d921f42ad48a40278443cd0bff87e96988f7e6ad571e463a056499`. Neither upstream acknowledgement nor the CUDA pass validates the fix for our short-text CPU case. That block was subsequently cleared for the tested September -12 image by the [fixed-image retest](CPU-RETEST-20260912.md), not by source review alone. +12 image by the [fixed-image retest](reports/CPU-RETEST-20260912.md), not by source review alone. The isolated CPU fresh-install test on 2026-09-06 started successfully and the native WebUI rendered, but browser model download failed because DockerMan's 99:100/0755 model directory was not writable by the image's UID 1000 user. -See [first-run findings](FIRST-RUN-FINDINGS.md) for exact image identity and +See [first-run findings](reports/FIRST-RUN-FINDINGS.md) for exact image identity and evidence. A subsequently approved `--user=99:100` experiment passed browser downloads, browser/API inference for all three variants, CPU/CUDA13 restart and -CUDA12 recreation checks. See [user-identity results](USER-IDENTITY-TESTS.md). +CUDA12 recreation checks. See [user-identity results](reports/USER-IDENTITY-TESTS.md). The local draft adopted the override in all three variants on 2026-09-07, with matching structural checks and setup guidance. Subsequent private UI and controlled CUDA 13 lifecycle results are recorded above. Full acceptance remains incomplete; @@ -214,7 +214,7 @@ the personal deployment passed a similar check. ## 1. Template and branch checks -The [UI preflight](UI-TEST-PREFLIGHT.md) found that installed CA 2026.07.21 private +The [UI preflight](reports/UI-TEST-PREFLIGHT.md) found that installed CA 2026.07.21 private apps do not expand branches. Pre-expanded private XMLs can test each variant's installation handoff, but the public selector needs a supported feed/preview workflow. An authenticated owner browser session is also required. diff --git a/docs/CPU-RETEST-20260912.md b/docs/reports/CPU-RETEST-20260912.md similarity index 100% rename from docs/CPU-RETEST-20260912.md rename to docs/reports/CPU-RETEST-20260912.md diff --git a/docs/FIRST-RUN-FINDINGS.md b/docs/reports/FIRST-RUN-FINDINGS.md similarity index 100% rename from docs/FIRST-RUN-FINDINGS.md rename to docs/reports/FIRST-RUN-FINDINGS.md diff --git a/docs/RECREATION-TEST.md b/docs/reports/RECREATION-TEST.md similarity index 100% rename from docs/RECREATION-TEST.md rename to docs/reports/RECREATION-TEST.md diff --git a/docs/SHORT-TEXT-INVESTIGATION.md b/docs/reports/SHORT-TEXT-INVESTIGATION.md similarity index 100% rename from docs/SHORT-TEXT-INVESTIGATION.md rename to docs/reports/SHORT-TEXT-INVESTIGATION.md diff --git a/docs/UI-TEST-PREFLIGHT.md b/docs/reports/UI-TEST-PREFLIGHT.md similarity index 100% rename from docs/UI-TEST-PREFLIGHT.md rename to docs/reports/UI-TEST-PREFLIGHT.md diff --git a/docs/UPDATE-ROLLBACK-TEST.md b/docs/reports/UPDATE-ROLLBACK-TEST.md similarity index 100% rename from docs/UPDATE-ROLLBACK-TEST.md rename to docs/reports/UPDATE-ROLLBACK-TEST.md diff --git a/docs/USER-IDENTITY-TESTS.md b/docs/reports/USER-IDENTITY-TESTS.md similarity index 100% rename from docs/USER-IDENTITY-TESTS.md rename to docs/reports/USER-IDENTITY-TESTS.md diff --git a/tests/test_publication.py b/tests/test_publication.py index bcde500..3b5e3e5 100644 --- a/tests/test_publication.py +++ b/tests/test_publication.py @@ -22,12 +22,13 @@ def candidate_files(): '.gitignore', 'CHANGELOG.md', 'LICENSE', 'README.md', 'CONTRIBUTING.md', 'SECURITY.md', 'assets/README.md', 'assets/icon.svg', 'assets/icon.png', 'ca_profile.xml', - 'docs/CONFIGURATION.md', 'docs/MAINTAINER.md', - 'docs/CPU-RETEST-20260912.md', 'docs/FIRST-RUN-FINDINGS.md', - 'docs/PLAN.md', 'docs/PUBLISHING.md', 'docs/RECREATION-TEST.md', 'docs/RELEASE-REVIEW.md', - 'docs/SHORT-TEXT-INVESTIGATION.md', 'docs/UI-TEST-PREFLIGHT.md', - 'docs/UPDATE-ROLLBACK-TEST.md', 'docs/USER-IDENTITY-TESTS.md', - 'docs/VALIDATION.md', 'templates/audio-cpp.xml', + 'docs/CONFIGURATION.md', 'docs/MAINTAINER.md', 'docs/RELEASE-REVIEW.md', + 'docs/VALIDATION.md', + 'docs/reports/CPU-RETEST-20260912.md', 'docs/reports/FIRST-RUN-FINDINGS.md', + 'docs/reports/RECREATION-TEST.md', 'docs/reports/SHORT-TEXT-INVESTIGATION.md', + 'docs/reports/UI-TEST-PREFLIGHT.md', 'docs/reports/UPDATE-ROLLBACK-TEST.md', + 'docs/reports/USER-IDENTITY-TESTS.md', + 'templates/audio-cpp.xml', 'tests/test_ci.py', 'tests/test_publication.py', 'tests/test_template.py', } @@ -38,16 +39,16 @@ def test_first_time_guide_keeps_safety_and_routes_advanced_notes(self): config = (ROOT / 'docs/CONFIGURATION.md').read_text() maintainer = (ROOT / 'docs/MAINTAINER.md').read_text() for heading in ('## What can I use it for?', '## Install on Unraid', - '## Make your first speech sample', '## Security'): + '## Make your first speech sample', '## Security', + '## Already installed?'): self.assertIn(heading, readme) - self.assertIn('no login or API authentication', readme) self.assertIn('(docs/RELEASE-REVIEW.md)', readme) self.assertIn('(docs/CONFIGURATION.md)', readme) self.assertIn('(docs/MAINTAINER.md)', readme) + # Tuning flags stay out of the first-time guide. self.assertNotIn('--max-loaded-models', readme) self.assertIn('--max-loaded-models', config) - self.assertIn('not yet been integration-tested', config) - self.assertIn('Run from the repository root', maintainer) + self.assertIn('python3 -m unittest discover -s tests', maintainer) def test_approved_licence_scopes(self): licence = (ROOT / 'LICENSE').read_text() @@ -56,8 +57,8 @@ def test_approved_licence_scopes(self): self.assertTrue(licence.startswith('MIT License\n')) self.assertIn('CC0-1.0', artwork) self.assertIn('https://creativecommons.org/publicdomain/zero/1.0/legalcode.en', artwork) - self.assertIn('to the extent they hold copyright and related rights', artwork) - self.assertIn('The icon is separately dedicated under CC0', readme) + self.assertIn('CC0', readme) + self.assertIn('(assets/README.md)', readme) def test_exact_candidate_inventory(self): actual = candidate_files() @@ -68,14 +69,6 @@ def test_exact_candidate_inventory(self): self.assertEqual(actual, EXPECTED, 'Review unexpected files before expanding the publication list') - def test_review_lists_exact_candidate(self): - review = (ROOT / 'docs/RELEASE-REVIEW.md').read_text() - manifest = re.search(r'```text\n(.*?)\n```', review, re.DOTALL) - self.assertIsNotNone(manifest) - entries = manifest.group(1).splitlines() - self.assertEqual(len(entries), len(set(entries))) - self.assertEqual(set(entries), EXPECTED) - def test_relative_markdown_links_stay_inside_candidate(self): for name in sorted(EXPECTED): if not name.endswith('.md'): diff --git a/tests/test_template.py b/tests/test_template.py index 442110c..a1a5a7d 100644 --- a/tests/test_template.py +++ b/tests/test_template.py @@ -189,7 +189,6 @@ def test_documented_release_gate(self): self.assertIn("lozenge0/audio-cpp-unraid", readme) self.assertIn("Beta integration", readme) self.assertIn("docs/RELEASE-REVIEW.md", readme) - self.assertTrue((ROOT / "docs/PLAN.md").is_file()) self.assertTrue((ROOT / "docs/VALIDATION.md").is_file()) self.assertIn("MIT License", (ROOT / "LICENSE").read_text())