docs: remove completed submodule-normalization handoff
The fork branch normalization it described is done — all local/sources forks are on submodule/* branches (submodule/relibc, submodule/base, ... in active use). Unreferenced one-time handoff; recoverable from git history if needed.
This commit is contained in:
@@ -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/<name>`. The `push-fork-branches.sh` script masked this because it pushes `HEAD:refs/heads/submodule/<fork>`, so `origin/submodule/<fork>` 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/<name>`. 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/<name>
|
||||
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/<name>` 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/<name>` 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/<name> | 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.
|
||||
Reference in New Issue
Block a user