vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update TOOLS.md for release-bump pipeline (5 new tools)

Browse Source 
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.
This commit is contained in:
vasilito
2026-07-18 14:48:53 +09:00
parent 99e5641127
commit f4ca523afd
1 changed files with 126 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
local/scripts/TOOLS.md
+126 -2
View File
@@ -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=<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
```
@@ -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=<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 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)