From b135dfdcd93cbc4c6c348434765dd6c3ac936743 Mon Sep 17 00:00:00 2001 From: vasilito Date: Tue, 14 Jul 2026 12:02:44 +0900 Subject: [PATCH] local/docs/SUBMODULE-NORMALIZATION-2026-07-13.md: operator handoff for fork branch normalization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 6 of 9 local fork working-trees are on branches that violate local/AGENTS.md § "BRANCH AND SUBMODULE POLICY": - 4 forks on master (bootloader, libredox, redoxfs, userutils) - 2 forks on version-suffixed branches (installer, syscall) Captures the exact 6-command fix, verification, and AGENTS.md policy citations. NO fallbacks, NO code changes — operator-only per "agents MUST NOT create new git branches" rule. (NO AI attribution) --- .../SUBMODULE-NORMALIZATION-2026-07-13.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 local/docs/SUBMODULE-NORMALIZATION-2026-07-13.md diff --git a/local/docs/SUBMODULE-NORMALIZATION-2026-07-13.md b/local/docs/SUBMODULE-NORMALIZATION-2026-07-13.md new file mode 100644 index 0000000000..d5ae12347a --- /dev/null +++ b/local/docs/SUBMODULE-NORMALIZATION-2026-07-13.md @@ -0,0 +1,107 @@ +# Submodule normalization handoff (2026-07-13) + +## Goal + +6 of 9 local fork working-trees are on branches that violate `local/AGENTS.md` § "BRANCH AND SUBMODULE POLICY". This doc captures the exact commands to bring all 9 forks to uniform state. + +## Current state (3 categories) + +| Fork | Working branch | Per AGENTS.md canonical | Divergence | +|------|----------------|-------------------------|------------| +| base | submodule/base | submodule/base | ✅ compliant | +| kernel | submodule/kernel | submodule/kernel | ✅ compliant | +| relibc | submodule/relibc | submodule/relibc | ✅ compliant | +| bootloader | master | submodule/bootloader | ❌ wrong | +| libredox | master | submodule/libredox | ❌ wrong | +| redoxfs | master | submodule/redoxfs | ❌ wrong | +| userutils | master | submodule/userutils | ❌ wrong | +| installer | installer-0.2.42-rb1 | submodule/installer | ❌ version-suffix policy violation | +| syscall | syscall-0.3.0 | submodule/syscall | ❌ version-suffix policy violation | + +## Root cause + +During operator-managed upstream rebase/sync sessions, work was done on `master` (or a version-suffixed branch) instead of `submodule/`. The `push-fork-branches.sh` script masked this because it pushes `HEAD:refs/heads/submodule/`, so `origin/submodule/` always has the right ref. The parent gitlink matches HEAD. No data is lost or divergent. + +## Why the parent repo's gitlink is fine + +`.gitmodules` declares all 9 forks with `branch = submodule/`. The parent tracks SHAs, not branches. As long as the SHA matches, the build works. The non-uniformity is purely cosmetic at the local worktree level. + +## Fix (operator-only, per AGENTS.md "Branch and Submodule Policy") + +The commands below are pure local branch renames. Zero build impact, zero data loss: + +```bash +# 4 forks on master → rename to canonical submodule/ +git -C local/sources/bootloader branch -m master submodule/bootloader +git -C local/sources/libredox branch -m master submodule/libredox +git -C local/sources/redoxfs branch -m master submodule/redoxfs +git -C local/sources/userutils branch -m master submodule/userutils + +# 2 forks on policy-violating version-suffixed branches → rename +git -C local/sources/installer branch -m installer-0.2.42-rb1 submodule/installer + +# syscall has a stale submodule/syscall branch locally that's 448 commits behind; +# delete it first, then rename +git -C local/sources/syscall branch -D submodule/syscall +git -C local/sources/syscall branch -m syscall-0.3.0 submodule/syscall +``` + +After each rename, the working-tree content is identical (branch rename doesn't touch files). + +## Verification + +After running the commands, verify uniform state: + +```bash +for f in base bootloader installer kernel libredox redoxfs relibc syscall userutils; do + cd /home/kellito/Builds/RedBear-OS/local/sources/$f + cur=$(git branch --show-current) + expected="submodule/$f" + if [ "$cur" = "$expected" ]; then + echo " ✓ $f: $cur" + else + echo " ✗ $f: $cur (expected $expected)" + fi + cd /home/kellito/Builds/RedBear-OS +done +``` + +Expected output: all 9 ✓. + +## Push the renamed branches + +The renamed branches need to be pushed to origin. Per `local/scripts/push-fork-branches.sh`, the push pattern is: + +```bash +./local/scripts/push-fork-branches.sh +``` + +(Or manually per fork: `git -C local/sources/$f push origin submodule/$f`.) + +The push will fast-forward the existing `origin/submodule/$f` refs to the new local SHAs (which are identical to the old SHAs — the rename doesn't change content). + +## Why this matters (re-cite AGENTS.md) + +From `local/AGENTS.md` line 195-205: +> "The **only** branches that exist in the `RedBear-OS` repo are: Release branches; Submodule branches (submodule/base, submodule/kernel, submodule/relibc, … (9 total)); Recovery branches." + +> "create a branch named after a version (e.g. redoxfs-0.9.0-rb1) — this is a **policy violation**. Version metadata lives in `Cargo.toml` version fields (as `+rbN` build metadata), not in branch names." + +The current state has 2 version-suffixed branches (`installer-0.2.42-rb1`, `syscall-0.3.0`) which are direct violations of this rule. The 4 `master` branches are not violations per se (master is a normal git branch) but the AGENTS.md table says the canonical is `submodule/` so working-trees should be on those. + +## When NOT to do this + +- Do NOT do this if any fork has uncommitted changes in its worktree (commit or stash first) +- Do NOT do this if the operator is mid-`push-fork-branches.sh` execution +- Do NOT do this if there's a Round 9+ push in progress (per `local/docs/fork-push-status/`) + +## Related open issue (NOT addressed by this fix) + +`base` push to origin deadlocks (gitea `receive.shallowUpdate=true`). Per `local/docs/fork-push-status/2026-07-12-Round-5-phase-4.1.md`. This requires operator intervention on the gitea server. The local branch rename in this doc does NOT solve the base push deadlock. + +## Status (as of 2026-07-13) + +- 3 of 9 forks compliant: base, kernel, relibc +- 6 of 9 forks need operator action +- 1 of 9 forks (base) has separate push-blocked issue requiring gitea server fix +- Fix ETA: 15 minutes of operator time, zero build disruption