RedBear-OS/local/docs/VERSIONING.md

Red Bear OS — External Recipe Versioning Model

This document defines how versions are managed for tar-based (external upstream) recipes under local/recipes/, and the machinery that keeps them consistent. It exists because a class of silent bug — a version bump that updated recipe metadata but never reached the actual build input — shipped the wrong version of Qt and the entire KDE stack (Qt built at 6.11.0 instead of 6.11.1; KDE built at 6.10.0 while recipes declared 6.28.0).

The two fork families

Red Bear OS carries local forks of upstream code in two places, each with its own consistency guard:

family	location	build input	version guard
source forks	local/sources/<comp> (submodules)	the fork branch	verify-fork-versions.sh, verify-fork-functions.sh
recipe forks	local/recipes/<name>/source/ (vendored tree)	the vendored source/	verify-external-source-versions.sh

This document is about the recipe forks.

Anatomy of a tar recipe

A tar recipe has up to four version-bearing artifacts:

1. recipe.toml → [source] tar = "…-<VER>.tar.xz" + blake3 + [package] version
2. source.tar — the downloaded pristine tarball
3. source/ — the vendored working tree, committed to git. For a vendored recipe this is pristine(VER) + recipe patches (+ occasionally a Redox change committed directly, a "baked shim"). This is what cookbook actually builds.
4. source/.redbear-src-version — a stamp recording the version source/ was laid down from.

A recipe is vendored if source/ is git-tracked, else transient (cookbook re-fetches + re-extracts from source.tar each build).

The invariant

recipe.toml is the single source of truth for the version. For a vendored recipe, source.tar, source/, and the .redbear-src-version stamp MUST all equal the version declared by [source] tar=.

recipe.toml is authoritative because it is the reviewable, diffable statement of intent. source/ is derived from it.

Why the invariant broke

bump-graphics-recipes.sh (and manual edits) rewrote tar=/blake3= but never propagated into the vendored source/. Cookbook, for its part, does not re-extract an existing source/ nor re-verify an existing source.tar against the recipe blake3. So a bump silently no-op'd on every vendored recipe: the metadata said the new version, the build kept compiling the old tree.

The machinery

sync-recipe-source.sh — the propagation engine

Makes source.tar + source/ + stamp agree with recipe.toml, by rebasing the vendored fork onto the declared upstream:

source/(Vnew) = pristine(Vnew) + recipe patches + captured baked delta

The baked delta is any change in the committed source/ not produced by a listed patch (e.g. a Redox shim committed directly). It is captured against pristine(Vold) and re-applied onto pristine(Vnew) so a re-lay can never silently drop a Redox port change; injected line-duplication corruption is dropped. A patch or shim that will not apply to the new upstream is reported as PATCH-REJECT/SHIM-REJECT (needs a manual rebase) — never applied with fuzz.

sync-recipe-source.sh --check --all      # triage every recipe, write nothing
sync-recipe-source.sh --commit <recipe>  # rebase + stamp + commit one recipe

verify-external-source-versions.sh — the preflight gate

Runs in build-preflight.sh (Phase 1.0C, skip with REDBEAR_SKIP_EXTERNAL_SOURCE_CHECK=1). Fails the build loudly on any divergence: source.tar blake3 ≠ recipe blake3, source.tar top-dir version ≠ tar-URL version, or vendored source/ marker/stamp ≠ tar-URL version.

bump-graphics-recipes.sh — now propagates

After rewriting tar=/blake3=/version, it calls sync-recipe-source.sh for the bumped recipe. A vendored recipe whose Redox port needs a manual rebase is reported ([propagate-manual]) rather than left silently stale.

How to bump an external recipe (the correct workflow)

1. Bump the version: bump-graphics-recipes.sh (auto, resolves latest) or edit recipe.toml's tar= by hand.
2. It propagates into source/ via the sync engine. If it reports [propagate-manual], rebase the failing patch/shim onto the new upstream and re-run sync-recipe-source.sh --commit <recipe>.
3. verify-external-source-versions.sh (in preflight) confirms consistency.

Source-version markers understood by the tooling

• source/.redbear-src-version — plain X.Y.Z (written by the sync engine)
• source/.cmake.conf → QT_REPO_MODULE_VERSION (Qt modules)
• source/CMakeLists.txt → set(KF_VERSION …) / project(… VERSION …) (KDE)