vasilito
f4ca523afd
Add documentation for the 5 new release-bump tools: - bump-release.sh (canonical orchestrator) - check-external-versions.sh (external version reporter) - bump-graphics-recipes.sh (map-driven graphics bumper) - post-checkout-version-sync.sh (opt-in branch hook) - install-git-hooks.sh (idempotent hook installer) Bump tool count 10 -> 15, round 13 -> 14. Apply drift fixes at lines 94-96 and 204.
10 KiB
Red Bear OS — Build System Tools Reference
Round 14 | 15 tools | local/scripts/
This is the canonical reference for build-system operator tools.
Test scripts (~120) are excluded; see local/scripts/test-*.sh
for QEMU/runtime validation helpers.
Quick Reference
| Tool | Purpose | Example |
|---|---|---|
| patch-status.sh | Consolidated status report | ./local/scripts/patch-status.sh (--brief, --json) |
| sync-versions.sh | Cat 0+1+2 version sync + lockfile regen | ./local/scripts/sync-versions.sh --check |
| verify-patch-content.py | Orphan patch detection + decision support | python3 local/scripts/verify-patch-content.py --report action |
| verify-fork-versions.sh | Cat 2 fork supremacy + content check | ./local/scripts/verify-fork-versions.sh |
| verify-collision-detection.py | Config files vs recipe installs/files collision | python3 local/scripts/verify-collision-detection.py --strict |
| pre-push-checks.sh | 7-check pre-push safety net (opt-in hook) | cp local/scripts/pre-push-checks.sh .git/hooks/pre-push |
| push-fork-branches.sh | Operator-reviewed fork push helper | ./local/scripts/push-fork-branches.sh (--execute) |
| unblock-base-push.sh | Base fork deadlock resolver (3 operator paths) | ./local/scripts/unblock-base-push.sh path-a |
| commit-msg | Auto-phase-prefix hook (opt-in) | cp local/scripts/commit-msg .git/hooks/commit-msg |
| build-preflight.sh | Build-time validation (called by build-redbear.sh) | ./local/scripts/build-preflight.sh --config=redbear-mini |
| bump-release.sh | Canonical release-bump orchestrator | ./local/scripts/bump-release.sh --with-sources --with-external |
| check-external-versions.sh | External desktop-stack version reporter | ./local/scripts/check-external-versions.sh --strict |
| bump-graphics-recipes.sh | Map-driven Qt6/KF6/Plasma recipe bumper | ./local/scripts/bump-graphics-recipes.sh --dry-run |
| post-checkout-version-sync.sh | Auto label-sync on semver branch switch (opt-in hook) | cp local/scripts/post-checkout-version-sync.sh .git/hooks/post-checkout |
| install-git-hooks.sh | Idempotent opt-in hook installer | ./local/scripts/install-git-hooks.sh --all |
Modes and Flags
patch-status.sh
--brief One-line summary: [orph=0/122 col=0 sync=OK fork=OK cargo=OK]
--json Machine-readable JSON
(default) Full text report with fork push status
sync-versions.sh
--check Verify only, exit 1 on drift
--regen Apply version sync + regen Cargo.lock files (opt-in)
--dry-run Preview: show what --regen WOULD change, revert after
--no-regen Apply version sync, skip Cargo.lock regen (same as default)
--regen-only Only regenerate Cargo.lock files
(default) Apply version sync only (lockfile regen is opt-in)
verify-patch-content.py
--strict Exit 1 on any orphan
--report action Operator-decision suggestions (INTEGRATED/SUPERSEDED/etc.)
--report detail Per-orphan listing with file paths
--selftest 5 regression test cases
(default) Per-component summary
verify-collision-detection.py
--strict Exit 1 on any collision
--selftest 8 regression test cases
(default) Per-config summary
verify-fork-versions.sh
REDBEAR_SKIP_FORK_VERIFY=1 Skip entirely
REDBEAR_STRICT_DIVERGED_CHECK=1 Treat diverged as ERROR
(default) Diverged = WARN (advisory)
pre-push-checks.sh
--soft Warn-only, don't block push
(default) Block push on any check failure
push-fork-branches.sh
--execute Actually push (default = print-only with 5-second abort)
(default) Show status + commands
bump-release.sh (canonical release-bump orchestrator)
bump-release.sh is the single entry point for a Red Bear OS release bump.
It DECIDES what needs to move (per-fork routing, external group) and
DELEGATES execution to existing single-purpose tools (sync-versions.sh
for label rewrites, upgrade-forks.sh --to=<tag> for source rebases,
bump-graphics-recipes.sh for the desktop stack). It never duplicates sed
logic and never auto-commits. See local/docs/RELEASE-BUMP-WORKFLOW.md
for the full runbook and decision tree.
(no args) Label sync (sync-versions.sh --no-regen) + fork upstream
REPORT. Fast, local + cached network. (The post-checkout
hook calls sync-versions.sh --no-regen directly — not this
script. External version report is only via --with-external
or a standalone check-external-versions.sh run.)
--with-sources Additionally perform fork source bumps for eligible
forks (mode snapshot/tracked, newer upstream semver tag)
via upgrade-forks.sh --to=<tag>, then re-sync labels and
update local/fork-upstream-map.toml column 3 in place.
--with-external Additionally run the rewritten bump-graphics-recipes.sh
for the Qt6/KF6/Plasma desktop stack (group-coherent).
--check Read-only: report drift + upgradeable-found; exit 1 if
any. CI-friendly.
--dry-run Print intended changes only; no file mutations.
--no-fetch Use cached upstream lookups; no network.
--regen Also regenerate Cargo.lock files (sync-versions.sh --regen).
--force-diverged Allow source-bump attempts on `diverged` forks
(kernel/bootloader/installer). Default = report-only.
--fork=<name> Scope to a single fork (e.g. --fork=relibc).
Map input: local/fork-upstream-map.toml (columns: name, url, tag, mode).
Never auto-commits. Prints exact commit commands (parent repo + the
relevant submodule/<fork> branch) for the operator to run.
check-external-versions.sh (external desktop-stack version reporter)
Reads local/external-upstream-map.toml ([groups.*] for Qt6/KF6/Plasma
and [packages.*] for singletons like mesa/libdrm/libwayland/sddm) and
resolves the latest published version per group/package. Index fetches are
cached under .redbear-recipe-bump/ so --no-fetch can reuse a prior run.
(no args) Print table: name current latest CURRENT|OUTDATED.
Exit 0 always (report).
--strict Exit 1 if any package is OUTDATED.
--no-fetch Reuse cached index from .redbear-recipe-bump/.
--json Emit machine-readable JSON instead of a table.
bump-graphics-recipes.sh (rewritten, map-driven)
Map-driven recipe bumper for the external desktop stack. Driven by
local/external-upstream-map.toml. Group version resolved ONCE per group
(Qt6/KF6/Plasma); per-recipe realpath dedup (symlinked recipes bumped
exactly once). tar sources: download → b3sum → sed tar = + blake3 =
(+ sync [package] version = if semver-mismatched). git-rev sources:
git ls-remote --tags → latest tag commit sha → sed rev =.
(no args) Apply bumps; run `repo validate-patches` per recipe;
write stabilization report to
.redbear-recipe-bump/last-report.txt.
--dry-run Print intended changes only (recipe= old= new=).
--no-fetch Reuse cached tarballs / index from .redbear-recipe-bump/.
Report format (one line per evaluated recipe):
recipe= old= new= patches_total= patches_pass= patches_fail= fail_details=
Never commits. Never removes a recipe for failing validation (per AGENTS.md ABSOLUTE RULE) — failures land in the report for the stabilization phase.
post-checkout-version-sync.sh (opt-in hook)
(installed as .git/hooks/post-checkout)
(no args) On semver branch switch with clean tree: run
sync-versions.sh --no-regen (labels only). Always
exits 0.
REDBEAR_NO_AUTO_SYNC=1 Bypass for a single checkout.
Guards: $3==1, anchored semver branch, no rebase/cherry-pick/merge in
progress, REDBEAR_NO_AUTO_SYNC unset, clean tree. Never network, never
regen, never commit. See local/docs/HOOKS.md.
install-git-hooks.sh (hook installer)
(no args) Install post-checkout only (default, least surprise).
--all Also install pre-push-checks.sh and commit-msg.
--uninstall Remove installed hooks (restores .bak if present).
--uninstall --all Remove the full --all set.
Idempotent: up-to-date installs are no-ops; differing existing hooks are
backed up to <name>.bak (rotated) before overwrite.
Where each tool runs
build-preflight.sh
├── sync-versions.sh --check
├── verify-fork-versions.sh
├── verify-patch-content.py
└── verify-collision-detection.py
pre-push-checks.sh (opt-in git hook)
├── sync-versions.sh --check
├── verify-fork-versions.sh
├── verify-patch-content.py
├── verify-patch-content.py --report action
├── verify-patch-content.py --selftest
├── verify-collision-detection.py
└── verify-collision-detection.py --selftest
post-checkout-version-sync.sh (opt-in git hook)
└── sync-versions.sh --no-regen (label-only; NEVER --regen)
bump-release.sh (canonical release-bump orchestrator)
├── sync-versions.sh --no-regen (labels)
├── update_map_tag_inplace() (in-script map column-3 update;
│ refresh-fork-upstream-map.sh is a
│ standalone complement that also
│ appends missing fork rows)
├── upgrade-forks.sh --to=<tag> (source bumps, --with-sources)
└── bump-graphics-recipes.sh (desktop stack, --with-external)
└── repo validate-patches <recipe>
install-git-hooks.sh (operator opt-in hook installer)
└── cp into .git/hooks/{post-checkout,pre-push,commit-msg}
See also
local/docs/HOOKS.md— git hooks documentationlocal/docs/RELEASE-BUMP-WORKFLOW.md— release-bump operator runbooklocal/docs/PATCH-PRESERVATION-AUDIT-2026-07-12.md— cumulative rounds 0-12local/fork-upstream-map.toml— fork → upstream tag/mode maplocal/external-upstream-map.toml— external desktop-stack version maplocal/patches/README.md— patch archive structure
Last updated: 2026-07-18 (Round 14 — release-bump pipeline)