BST Junction Overrides#

Load when creating, evaluating, or removing BuildStream junction element overrides in projectbluefin/dakota.

Core Principle: Upstream-First#

Dakota inherits most elements from gnome-build-meta (GBM) and freedesktop-sdk (fdsdk) via BST junctions. The correct workflow is always:

1. Check if upstream already has the fix — if yes, bump the junction ref
2. Submit a fix upstream — patch the upstream project, reference the upstream PR
3. Override locally as a last resort — only when upstream won't or can't fix in time

Local overrides are maintenance debt. Every override needs an exit condition.

What Is a Junction Override?#

By default, elements/gnome-build-meta.bst and elements/freedesktop-sdk.bst use the refs from the upstream junction. An override replaces a specific upstream element with a local version.

Do NOT edit junction .bst files directly. Overrides are applied via patch_queue source in the junction file, or by providing a local element that shadows the junction element.

Override Patterns#

Patch Queue Override (Preferred)#

For changes that should eventually go upstream, add a patch to the junction's patch_queue:

# In elements/gnome-build-meta.bst
sources:
- kind: git_repo
  ...
- kind: patch_queue
  path: patches/gnome-build-meta

Patches in patches/gnome-build-meta/ apply in alphabetical (filename) order. See patch-junctions.md for the full patch lifecycle.

Element Shadow Override#

To completely replace an upstream element, create a local element at the same path the junction would provide. Use sparingly.

Evaluating Whether to Override#

Exit Conditions#

Every override file must have an exit condition comment:

# Exit condition: Drop after fdsdk ships X release
# Exit condition: Drop once gnome-build-meta gnome-50 merges MR !NNN
# Exit condition: Permanent — dakota-specific, not upstreamable

Without an exit condition, the override becomes permanent maintenance debt with no path to removal.

Checking Upstream Status#

# Check if a fix is already in GBM gnome-50:
gh api repos/GNOME/gnome-build-meta/commits?sha=gnome-50 | jq '.[].commit.message' | grep -i <fix>

# Check if fdsdk has the fix in their latest tag:
gh api repos/freedesktop-sdk/freedesktop-sdk/releases/latest | jq '.tag_name'

Lessons Learned#

Alphabetical patch ordering matters — 0004 is higher priority than 0003 (2026-06-07)#

Patch files in patches/<junction>/ apply in alphabetical (filename) order. Gaps in numbering
are intentional — they leave room to insert patches between existing ones without renaming. Do
not fill gaps just to make the sequence look clean:

patches/freedesktop-sdk/
  0001-project-Specify-more-limits-to-the-CAS-configs.patch
  0002-project.conf-Add-GNOME-CAS-servers.patch
  0004-openssh-Use-etc-ssh-as-sysconfdir.patch ← gap is intentional
  0005-openssh-Include-ssh-_config.d-.conf.patch

When inserting a new patch between 0004 and 0005, name it 0004b-... or 0004c-... so the
alphabetical order is preserved without renaming 0005+.

gnome-build-meta currently has only one patch — it's not a typo (2026-06-07)#

patches/gnome-build-meta/disable-lorry-mirrors.patch is the only GBM patch. Dakota tracks
the most recent GBM ref (latest nightly), which means most fixes are already upstream. The
single-patch state is healthy — it means minimal maintenance debt.

Verify upstream before adding a patch (2026-06-07)#

Before adding a new patch to patches/<junction>/:

# Check if fdsdk already has the fix on their latest tag:
gh api repos/freedesktop-sdk/freedesktop-sdk/releases/latest | jq '.tag_name'

# Check if GBM gnome-50 already has the fix:
git -C ~/.cache/buildstream/sources/git_repo/<gbm-mirror>.git \
  log --oneline origin/gnome-50 | head -20

Adding a patch for something already upstream wastes maintenance cycles — junction bump is
cheaper.