diff --git a/local/docs/SUBMODULE-NORMALIZATION-2026-07-13.md b/local/docs/SUBMODULE-NORMALIZATION-2026-07-13.md deleted file mode 100644 index 49c9bc03fb..0000000000 --- a/local/docs/SUBMODULE-NORMALIZATION-2026-07-13.md +++ /dev/null @@ -1,140 +0,0 @@ -# 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 - ---- - -## Round-21 execution (post-authorization) - -Operator authorized execution of the fix above. Result: - -| Fork | Before | After | Push to origin | -|------|--------|-------|----------------| -| bootloader | master | submodule/bootloader | ✓ fast-forward | -| libredox | master | submodule/libredox | ✓ fast-forward | -| redoxfs | master | submodule/redoxfs | ✓ fast-forward | -| userutils | master (had stale divergent local submodule/userutils ref at 237d28b vs HEAD 0dc0cb7) | submodule/userutils | ✓ force-push (local ref reset to HEAD; same SHA operator already had) | -| installer | installer-0.2.42-rb1 (policy violation: version-suffixed branch) | submodule/installer | ✓ fast-forward | -| syscall | syscall-0.3.0 (policy violation: version-suffixed branch) | submodule/syscall (deleted stale divergent local ref first) | ✓ fast-forward | -| kernel | submodule/kernel (already compliant) | submodule/kernel | ✓ fast-forward (was 1 commit ahead of origin — diag(kernel) trace commit) | -| relibc | submodule/relibc (already compliant) | submodule/relibc | ✓ fast-forward (was 11 commits ahead of origin — FILETABLE fix series) | -| base | submodule/base (already compliant) | submodule/base | ✗ rejected (non-fast-forward) — known gitea deadlock | - -**Final state**: 9 of 9 forks on `submodule/` branches per AGENTS.md policy. 8 of 9 local == origin. Base push remains blocked on the known gitea `receive.shallowUpdate=true` issue requiring operator server fix. - -**What was NOT done** (per AGENTS.md policy): -- 0 new branches created (`git branch -m` only renames) -- 0 rebases or history rewrites -- 0 force-pushes on base (respected the known deadlock) -- 0 fork source modifications - -**Per-fork structure verified** via `git log --oneline submodule/ | head -3`: all 9 forks end with Red Bear commits (`rb:`, `0.3.1: bump version`, etc.) or version-suffix bumps (`Cargo.lock: regenerate`) layered on top of upstream merges. Structure matches `local/fork-upstream-map.toml` snapshot pattern: upstream commits at base, Red Bear patches layered on top. - -**Parent repo state**: clean. No parent commit was needed — the 6 fork renames didn't change SHAs (rename only), and the 2 forks with origin-lag (kernel, relibc) had their parent gitlinks already tracking the worktree SHAs via prior operator commits (`314f655f37` for kernel, `e38b1bac27` for relibc). - -**Carry-over (still open)**: -- Base push deadlock: requires operator intervention on gitea server to disable `receive.shallowUpdate=true`. Local work complete; remote push blocked until server config change.