Skip to content
Closed
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
7 changes: 3 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,9 @@ checks (`scripts/check-skill-frontmatter.sh`, `scripts/check-skill-index.sh`,

## Invariants — do not break

- **`packages/bluefin.toml` is a byte-for-byte copy** of
`projectbluefin/bluefin` `build_files/packages/base.toml`. Never hand-edit
it; sync it verbatim from upstream. CI diffs it on every run
(`just check-parity`).
- **`packages/bluefin.toml` is derived from Bluefin's effective package payload**
(base, version-specific, external, and multimedia transactions).
CI verifies it against upstream on every run (`just check-parity`).
- **Utah's own package changes live in `packages/utah.toml`** (`[gnome]`,
`[build]`, `[unavailable]`). Every `[unavailable]` entry MUST carry a
tracking issue. A missing contract package is a build failure, never a
Expand Down
19 changes: 5 additions & 14 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ check:
python3 -m py_compile scripts/install-packages.py
python3 -m py_compile scripts/verify-rpm-contract.py
python3 -m py_compile scripts/check-repo-availability.py
python3 -m py_compile scripts/check-parity.py
python3 scripts/install-packages.py --check packages/bluefin.toml
python3 scripts/verify-rpm-contract.py --check packages/bluefin.toml
grep -qE 'reusable-build\.yml@(v1|[0-9a-f]{40} # v1)$' .github/workflows/build.yml
Expand Down Expand Up @@ -109,21 +110,11 @@ check-desktop-contract image_ref="localhost/utah:testing":
check-repos:
python3 scripts/check-repo-availability.py packages/bluefin.toml packages/utah.toml

# packages/bluefin.toml is a verbatim copy of Bluefin's base.toml. Drift here
# is a parity bug, so make it loud rather than letting it accumulate quietly.
# packages/bluefin.toml is derived from Bluefin's effective package payload
# (base, version-specific, external, and multimedia transactions).
# Drift here is a parity bug, so make it loud rather than letting it accumulate quietly.
check-parity:
#!/usr/bin/env bash
set -euo pipefail
upstream=$(mktemp)
trap 'rm -f "$upstream"' EXIT
curl -fsSL -o "$upstream" \
https://raw.githubusercontent.com/projectbluefin/bluefin/main/build_files/packages/base.toml
if diff -u "$upstream" packages/bluefin.toml; then
echo "packages/bluefin.toml matches projectbluefin/bluefin"
else
echo "packages/bluefin.toml has drifted from projectbluefin/bluefin" >&2
exit 1
fi
python3 scripts/check-parity.py

image_name base_name stream flavor:
#!/usr/bin/env bash
Expand Down
12 changes: 7 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,15 +47,17 @@ is built to produce, not something you can pull today.

## Package parity with Bluefin

`packages/bluefin.toml` is a byte-for-byte copy of Bluefin's `base.toml`, and CI
diffs it against upstream on every run, so drift fails the build rather than
being noticed later.
`packages/bluefin.toml` is a machine-readable contract derived from Bluefin's
effective package payload (covering base Fedora, version-specific, external,
and multimedia transactions). CI derives and verifies it against upstream on
every run (`just check-parity`), so additions or removals fail the build rather
than accumulating quietly.

| | count |
| --- | --- |
| Bluefin contract installed | **61** |
| Bluefin contract installed | **64** |
| Utah additions (GNOME 51, desktop services) | 12 |
| Genuinely unavailable | **4** |
| Documented unavailable exceptions | **28** |

The install writes its resolved list to `/usr/share/utah/contract.txt` and the
verify step asserts *that file*, so the two cannot disagree.
Expand Down
8 changes: 4 additions & 4 deletions docs/skills/index.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"generated_at": "2026-09-05",
"generated_at": "2026-09-11",
"schema_version": "1.0",
"skills": [
{
Expand Down Expand Up @@ -123,9 +123,9 @@
"bluefin",
"contracts"
],
"description": "Bluefin parity contract: verbatim bluefin.toml, utah.toml overlay, [unavailable] rules, repository policy. Use when adding, removing, or debugging packages or parity/check-repos failures.",
"version": "1.0",
"last_updated": "2026-09-05",
"description": "Bluefin parity contract: machine-readable effective payload bluefin.toml, utah.toml overlay, [unavailable] rules, repository policy. Use when adding, removing, or debugging packages or parity/check-repos failures.",
"version": "1.1",
"last_updated": "2026-09-11",
"doc_type": "policy"
},
{
Expand Down
2 changes: 1 addition & 1 deletion docs/skills/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
This file is a human-readable mirror of `index.json`. Both are generated by
`scripts/generate_skill_index.py` — do not hand-edit either file.

Generated: 2026-09-05 · schema 1.0 · 8 skills
Generated: 2026-09-11 · schema 1.0 · 8 skills

| id | category | status | one-line purpose |
|---|---|---|---|
Expand Down
59 changes: 29 additions & 30 deletions docs/skills/package-contract.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: package-contract
version: "1.0"
last_updated: "2026-09-05"
version: "1.1"
last_updated: "2026-09-11"
id: package-contract
one_line_purpose: Maintain Bluefin package parity and Utah's overlay manifest.
entry_point: docs/skills/package-contract.md
Expand All @@ -12,9 +12,9 @@ status: active
dependencies: []
tags: [packages, parity, bluefin, contracts]
description: >-
Bluefin parity contract: verbatim bluefin.toml, utah.toml overlay,
[unavailable] rules, repository policy. Use when adding, removing, or
debugging packages or parity/check-repos failures.
Bluefin parity contract: machine-readable effective payload bluefin.toml,
utah.toml overlay, [unavailable] rules, repository policy. Use when adding,
removing, or debugging packages or parity/check-repos failures.
metadata:
type: policy
---
Expand All @@ -27,20 +27,23 @@ policy for changing them.

## The two manifests

- **`packages/bluefin.toml`** — the parity contract. It is a byte-for-byte
copy of projectbluefin/bluefin's `build_files/packages/base.toml` and must
stay that way. **Never hand-edit it.** Sync it verbatim from upstream; any
drift is a parity bug. `just check-parity` diffs it against upstream on
every CI run so drift fails the build rather than accumulating quietly
(recipe comment: `Justfile`, `check-parity`).
- **`packages/bluefin.toml`** — the parity contract. It is a machine-readable
contract derived from the package transactions that Bluefin actually executes:
base Fedora packages, version-specific additions, external/COPR transactions
(such as `tailscale` and `uupd`), and multimedia transactions (including
overrides and codecs). **Never hand-edit it without validation.**
`just check-parity` runs `scripts/check-parity.py` on every CI run, deriving
the effective payload from upstream Bluefin's `build_files/packages/base.toml`
and `build_files/base/03-packages.sh` to detect additions and removals.
- **`packages/utah.toml`** — Utah's overlay. Everything Utah needs *in
addition to* or *instead of* the contract lives here. The full rules are in
the header comment of that file (cite it; do not move or copy it):

- `[gnome]` — GNOME 51 desktop contract Hummingbird does not ship.
- `[build]` — toolchain needed to build the pinned GNOME extensions
(`scripts/build-gnome-extensions.sh`).
- `[services]` — desktop services Bluefin adds on top of the server base.
- `[services]` — desktop services Hummingbird's server base does not install
(`fwupd`, `systemd-resolved`).
- `[unavailable]` — Bluefin contract packages none of Utah's repositories
provide.

Expand All @@ -51,23 +54,19 @@ policy for changing them.
a dumping ground for packages that are merely inconvenient (header comment,
`packages/utah.toml`).

## multimedia_overrides are not missing packages
## Multimedia transactions and overrides

Bluefin's `[multimedia_overrides]` (twelve names: mesa-libGL,
mesa-vulkan-drivers, libva, intel-mediasdk, libheif and friends) are **not**
extra packages. They are the same names Fedora already ships, which Bluefin
*replaces* with negativo17 builds by enabling `fedora-multimedia`. Utah does
not enable that repository, so it installs Fedora's builds instead. Nothing
is absent from the image; what differs is which build it carries, and the
practical consequence is hardware-accelerated codec support.
Bluefin executes an extensive multimedia transaction combining negativo17's
`fedora-multimedia` repository overrides (`mesa`, `libva`, etc.) and codecs
(`ffmpeg`, `gstreamer1-plugins-*`, `lame`, `libfdk-aac`, `libjxl`). Utah does
not enable negativo17 or Fedora runtime repositories.

That is why they are absent from the contract rather than listed under
`[unavailable]`: recording them as missing would be wrong (a source does
provide the name), and recording them as satisfied would hide a real
functional difference. The factory already builds several of them in
projectbluefin/hummingbird-github; when that overlay is published and enabled
here, these can move into the contract as a version assertion rather than a
name one (header comment, `packages/utah.toml`).
Where Hummingbird or `utah-packages` already provides the required build
(`intel-gmmlib`, `intel-mediasdk`, `intel-vpl-gpu-rt`, `libheif`, `libva`),
Utah installs it directly as part of the contract. Packages not yet available
in Utah's enabled repositories are recorded in `[unavailable]` with tracking
issue #12, until the complete multimedia closure from `utah-packages#24` is
published.

## Repository policy

Expand Down Expand Up @@ -114,9 +113,9 @@ about installation.
- Drift in `packages/bluefin.toml` from upstream is a CI failure
(`just check-parity`).

Current counts, per the README "Package parity" section: 61 Bluefin contract
packages installed, 12 Utah additions (GNOME 51, desktop services), 4
genuinely unavailable.
Current counts: 64 Bluefin contract packages installed (58 fedora base +
1 fedora_v44 + 5 multimedia overrides), 12 Utah additions (10 GNOME 51,
2 desktop services), 28 documented as unavailable.

## Verification

Expand Down
89 changes: 60 additions & 29 deletions packages/bluefin.toml
Original file line number Diff line number Diff line change
@@ -1,34 +1,21 @@
# Package manifest for the bluefin base image.
# Read by build_files/base/03-packages.sh via build_files/shared/read-packages.
# Machine-readable contract derived from Bluefin's effective package payload.
#
# Sources in projectbluefin/bluefin:
# - build_files/packages/base.toml (fedora, version-specific, overrides, excluded)
# - build_files/base/03-packages.sh (external and multimedia transactions)
#
# Sections:
# [multimedia_overrides] packages synced from fedora-multimedia repo
# [fedora] base Fedora packages, all versions
# [fedora_v42] additions for Fedora 42 only
# [fedora_v43] additions for Fedora 43 only
# [fedora_v44] additions for Fedora 44 only
# [fedora] base Fedora packages common to all supported versions
# [fedora_v*] version-specific Fedora additions
# [external] packages from external repositories/COPRs
# [multimedia] codecs and multimedia packages from 03-packages.sh
# [multimedia_overrides] packages synced from negativo17/fedora-multimedia
# [excluded] packages removed from the base image
#
# Validated by scripts/check-parity.py on every CI run (`just check-parity`).

[multimedia_overrides]
# Replace mesa and friends with less-crippled versions from negativo17/fedora-multimedia.
# Versions are pinned with `dnf5 versionlock` after install.
packages = [
"intel-gmmlib",
"intel-mediasdk",
"intel-vpl-gpu-rt",
"libheif",
"libva",
"libva-intel-media-driver",
"mesa-dri-drivers",
"mesa-filesystem",
"mesa-libEGL",
"mesa-libGL",
"mesa-libgbm",
"mesa-vulkan-drivers",
]

[fedora]
# Base packages from Fedora repos — common to all supported Fedora versions.
[fedora]
packages = [
"adw-gtk3-theme",
"adwaita-fonts-all",
Expand All @@ -43,10 +30,10 @@ packages = [
"dracut-live",
"evtest",
"fastfetch",
"firefox",
"firewall-config",
"fish",
"flatpak-spawn",
"firefox",
"fzf",
"gcc",
"gcc-c++",
Expand Down Expand Up @@ -95,25 +82,69 @@ packages = [
"zsh",
]

# Fedora 42 additions
[fedora_v42]
# TODO: remove when F42 is dropped
packages = [
"evolution-ews-core",
]

# Fedora 43 additions
[fedora_v43]
packages = [
"evolution-ews-core",
"gnupg2-scdaemon",
]

# Fedora 44 additions
[fedora_v44]
packages = [
"gnupg2-scdaemon",
]

[excluded]
# External and COPR packages installed in Bluefin's package transaction.
[external]
packages = [
"tailscale",
"uupd",
]

# Codecs and extra multimedia packages installed in Bluefin's transaction.
[multimedia]
packages = [
"@multimedia",
"ffmpeg",
"ffmpeg-libs",
"ffmpegthumbnailer",
"gstreamer1-plugins-bad-free",
"gstreamer1-plugins-bad-free-libs",
"gstreamer1-plugins-base",
"gstreamer1-plugins-good",
"lame",
"lame-libs",
"libavcodec",
"libfdk-aac",
"libjxl",
]

# Packages synced from negativo17/fedora-multimedia repo.
[multimedia_overrides]
packages = [
"intel-gmmlib",
"intel-mediasdk",
"intel-vpl-gpu-rt",
"libheif",
"libva",
"libva-intel-media-driver",
"mesa-dri-drivers",
"mesa-filesystem",
"mesa-libEGL",
"mesa-libGL",
"mesa-libgbm",
"mesa-vulkan-drivers",
]

# Packages removed from the base image — conflicts with or replaced by image content.
[excluded]
packages = [
"default-fonts-cjk-sans",
"fedora-bookmarks",
Expand Down
Loading