diff --git a/docs/skills/desktop-contract.md b/docs/skills/desktop-contract.md index d0a625903..7ce22c3f2 100644 --- a/docs/skills/desktop-contract.md +++ b/docs/skills/desktop-contract.md @@ -246,13 +246,13 @@ for the live image's own `installer-local` remote. Bluefin's GNOME extension submodules are retained with their normal build step. `.gitmodules` pins all 16 extension trees by URL and branch under -`system_files/shared/usr/share/gnome-shell/extensions/`. The weekly -`update-gnome-extensions.yml` workflow advances the configured branches and -opens a review PR; edit `.gitmodules` directly when changing a source or its -tracked branch. Search Light was dropped: -its shader code calls `set_shader_source`, which GNOME 51 removed, so the -extension errored at load and failed the ISO end-to-end test on every -flavor. +The weekly `.github/workflows/update-gnome-extensions.yml` workflow opens or +updates review PRs with old/new commits and each extension's declared GNOME +Shell versions. Its contract-only check validates source metadata; it does not +build an image or run the installed extension verifier. A full image build +must verify proposed pins before merge. Edit `.gitmodules` directly for source +URL or tracked-branch changes; automation only advances existing pins. +Search Light was dropped: GNOME 51 removed `set_shader_source`, which its shader code calls, so it failed ISO tests. `scripts/verify-gnome-extensions.py` asserts every one declares GNOME 51 in its `metadata.json`. It runs in two modes from the same script: @@ -469,32 +469,8 @@ flashing still goes through the daemon, which keeps its existing root lifecycle. The pairing is asserted by `FwupdRefreshDropInTests` in `tests/test_desktop_contract.py`. -## The verifiers run twice - -The same verifier runs in the Containerfile and on demand, so a local image -or a CI artifact can be checked after the fact (recipe comment, `Justfile`, -`check-desktop-contract`): - -- **In the image build** — the desktop RUN step ends with - `utah-verify-desktop-contract /usr/share/utah/bluefin-desktop.toml`, after - branding and services are configured; a contract failure fails the build. - The extension verifier runs earlier in the same step. -- **On demand** — `just check-desktop-contract ` (default - `localhost/utah:testing`) podman-runs both verifiers inside an - already-composed image: both verifiers and the desktop contract are - bind-mounted read-only from the working tree under `/tmp`. The extension - verifier uses installed mode to check the image's bundled extensions. - Build-time helpers under `/usr/local/libexec` are unavailable after - `clean-stage.sh` removes `/var/usrlocal` (the target of `/usr/local`), so - on-demand checks must not depend on those helpers surviving cleanup. -- **Off-image** — `verify-desktop-contract.py --check` validates the contract - TOML itself in source-only CI and is part of `just check`; it asserts - nothing about any image. - ## Verification -```bash -python3 scripts/verify-desktop-contract.py --check contracts/bluefin-desktop.toml -python3 scripts/verify-gnome-extensions.py --source -just check-desktop-contract localhost/utah:testing # requires a locally built image -``` +The source-only contract check runs in `just check`; the +[verifier reference](desktop-contract/references/verifiers.md) describes the +image-build and installed-image checks. diff --git a/docs/skills/desktop-contract/references/verifiers.md b/docs/skills/desktop-contract/references/verifiers.md new file mode 100644 index 000000000..9e68707e0 --- /dev/null +++ b/docs/skills/desktop-contract/references/verifiers.md @@ -0,0 +1,29 @@ +# Desktop contract verifiers + +The same verifier runs in the Containerfile and on demand, so a local image +or a CI artifact can be checked after the fact (recipe comment, `Justfile`, +`check-desktop-contract`): + +- **In the image build** — the desktop RUN step ends with + `utah-verify-desktop-contract /usr/share/utah/bluefin-desktop.toml`, after + branding and services are configured; a contract failure fails the build. + The extension verifier runs earlier in the same step. +- **On demand** — `just check-desktop-contract ` (default + `localhost/utah:testing`) podman-runs both verifiers inside an + already-composed image: both verifiers and the desktop contract are + bind-mounted read-only from the working tree under `/tmp`. The extension + verifier uses installed mode to check the image's bundled extensions. + Build-time helpers under `/usr/local/libexec` are unavailable after + `clean-stage.sh` removes `/var/usrlocal` (the target of `/usr/local`), so + on-demand checks must not depend on those helpers surviving cleanup. +- **Off-image** — `verify-desktop-contract.py --check` validates the contract + TOML itself in source-only CI and is part of `just check`; it asserts + nothing about any image. + +## Verification + +```bash +python3 scripts/verify-desktop-contract.py --check contracts/bluefin-desktop.toml +python3 scripts/verify-gnome-extensions.py --source +just check-desktop-contract localhost/utah:testing # requires a locally built image +```