vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d945483915ef55f76f1891dcd989c434287a32c3
RedBear-OS/local/scripts/TOOLS.md
T
vasilito f4ca523afd 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.
2026-07-18 14:48:53 +09:00

229 lines
10 KiB
Markdown
Raw Blame History

# 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 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-18 (Round 14 — release-bump pipeline)
Reference in New Issue View Git Blame Copy Permalink