From f4ca523afdc2cac7962e0d20f5b4bbb927e593be Mon Sep 17 00:00:00 2001 From: vasilito Date: Sat, 18 Jul 2026 14:48:53 +0900 Subject: [PATCH] docs: update TOOLS.md for release-bump pipeline (5 new tools) 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. --- local/scripts/TOOLS.md | 128 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 126 insertions(+), 2 deletions(-) diff --git a/local/scripts/TOOLS.md b/local/scripts/TOOLS.md index e1fd9339a1..f3646f1af5 100644 --- a/local/scripts/TOOLS.md +++ b/local/scripts/TOOLS.md @@ -1,6 +1,6 @@ # Red Bear OS — Build System Tools Reference -**Round 13** | **10 tools** | `local/scripts/` +**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` @@ -20,6 +20,11 @@ for QEMU/runtime validation helpers. | **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 @@ -75,6 +80,106 @@ REDBEAR_STRICT_DIVERGED_CHECK=1 Treat diverged as ERROR (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=` 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=, 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= 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/` 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 `.bak` (rotated) before overwrite. + ## Where each tool runs ``` @@ -92,13 +197,32 @@ pre-push-checks.sh (opt-in git hook) ├── 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= (source bumps, --with-sources) + └── bump-graphics-recipes.sh (desktop stack, --with-external) + └── repo validate-patches + +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 documentation +- `local/docs/RELEASE-BUMP-WORKFLOW.md` — release-bump operator runbook - `local/docs/PATCH-PRESERVATION-AUDIT-2026-07-12.md` — cumulative rounds 0-12 +- `local/fork-upstream-map.toml` — fork → upstream tag/mode map +- `local/external-upstream-map.toml` — external desktop-stack version map - `local/patches/README.md` — patch archive structure --- -**Last updated:** 2026-07-12 (Round 13) +**Last updated:** 2026-07-18 (Round 14 — release-bump pipeline)