Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 10 additions & 34 deletions docs/skills/desktop-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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 <ref>` (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.
29 changes: 29 additions & 0 deletions docs/skills/desktop-contract/references/verifiers.md
Original file line number Diff line number Diff line change
@@ -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 <ref>` (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
```
Loading