From 98ee3e4cca0a545cf412099e6af4aee80f664b22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABtan=20Trellu?= Date: Fri, 11 Sep 2026 14:38:35 -0400 Subject: [PATCH] docs: say that compose/ is a published interface, and what on-push diffs from Nothing in the README said that the compose files are consumed by another project. The OVOS installer clones this repository at a release tag and runs them, which makes the compose file names, the container names it execs into, the environment variables the compose reads and the images it pulls an interface somebody else depends on - and contract.yml declares all four so the dependency cannot drift unnoticed. A contributor editing compose/ had no way to learn that from here, or that scripts/contract.py has to be rerun afterwards. The automation table said on-push.yml builds what changed on a commit to dev. It builds what changed since the last commit the workflow actually published, which is not the same base whenever a run was cancelled - and cancelled runs are exactly when the difference matters, because the work would otherwise be skipped for good rather than retried. Both platform READMEs linked to README.md#how-to-use-these-images, a heading README.md does not have and has not had for years. The section a reader wants is Run images. Co-Authored-By: Claude Opus 5 --- README.md | 9 ++++++++- README_MACOS.md | 2 +- README_WINDOWS.md | 2 +- 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 316de8dd..3497652c 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,13 @@ All Python images share `ovos-base` (Debian slim, Python 3.13, a virtual environ pinned [uv](https://github.com/astral-sh/uv)). Each image has a `HEALTHCHECK`, an SBOM, a provenance attestation, and a cosign signature. +The compose files under `compose/` are consumed by other projects, not only by people: the +[OVOS installer](https://github.com/OpenVoiceOS/ovos-installer) clones this repository at a +release tag and runs them. The compose file names, the container names, the environment +variables the compose reads and the images it pulls are therefore a published interface, and +`contract.yml` declares all four. Run `scripts/contract.py --write` after editing `compose/`; +CI fails when the declaration and the compose files disagree. + ## Talking to OVOS from a terminal The `ovos-cli` image ships [ovos-tui-client](https://github.com/andlo/ovos-tui-client), @@ -128,7 +135,7 @@ multi-arch manifest lists. The workflows are in `.github/workflows/`: | Workflow | Trigger | What it builds | |---|---|---| -| `on-push.yml` | A commit on `dev` | The targets whose build context changed, plus the targets built on top of them, for `alpha`, `testing`, and `stable` | +| `on-push.yml` | A commit on `dev` | The targets whose build context changed since the last commit this workflow published, plus the targets built on top of them, for `alpha`, `testing`, and `stable` | | `on-constraints.yml` | A `repository_dispatch` from ovos-releases, an hourly poll, or a manual run | For each channel, the images that contain a package whose `constraints-.txt` line changed since the last build | | `pull-request.yml` | A pull request | The affected targets, for both architectures, without a push | | `scheduled-rebuild.yml` | Once a week | Every image of a channel | diff --git a/README_MACOS.md b/README_MACOS.md index 78c9287f..faced5c1 100644 --- a/README_MACOS.md +++ b/README_MACOS.md @@ -124,7 +124,7 @@ PulseAudio may use a different audio output (sink) than the one actually used by ## How to use these images -Please refer to [this section](README.md#how-to-use-these-images) of the documentation. +Please refer to [this section](README.md#run-images) of the documentation. ## Thanks diff --git a/README_WINDOWS.md b/README_WINDOWS.md index 5ec056c4..4d30afec 100644 --- a/README_WINDOWS.md +++ b/README_WINDOWS.md @@ -69,7 +69,7 @@ Time per period = 3.278807 ## How to use these images -Please refer to [this section](README.md#how-to-use-these-images) of the documentation. +Please refer to [this section](README.md#run-images) of the documentation. ## Thanks