STUBS-FIX-PROGRESS: document Red Bear forks vs. direct edits architectural decision (12 forks in place)
This commit is contained in:
@@ -459,3 +459,181 @@ Two agents refused to perform tasks that would have been policy violations:
|
||||
**New forks:** 4 (libdrm, redox-drm, pipewire, wireplumber) at `local/sources/`.
|
||||
**New local/recipes subdirectories:** `data/`, `wayland/`, `libs/redbear-qml-runtime/` (planned), `libs/pipewire/`, `libs/wireplumber/`, `libs/libxkbcommon/`, `drivers/redbear-hid-core/`.
|
||||
|
||||
---
|
||||
|
||||
## Architectural Decision: Red Bear Forks vs. Direct Edits (2026-06-09)
|
||||
|
||||
This section records the policy decision for **where Red Bear source modifications must live**.
|
||||
It is the durable, in-tree statement of the two-rule model already encoded in
|
||||
`local/AGENTS.md` under "NO OVERLAY-STYLE PATCHES — SCOPED POLICY (AMENDED 2026)".
|
||||
|
||||
### The policy in one sentence
|
||||
|
||||
> **Big external projects (mesa, wayland, qt, KF6, KWin, SDDM, llvm, libdrm, redox-drm, libepoxy,
|
||||
> pipewire, wireplumber, …) must live as Red Bear forks at `local/sources/<component>/`, not as
|
||||
> direct edits inside the mainline `recipes/<pkg>/source/` tree.**
|
||||
|
||||
### Why
|
||||
|
||||
Direct edits to `recipes/<pkg>/source/` are **clobbered by `make clean` and by upstream syncs**.
|
||||
A Red Bear fork at `local/sources/<component>/` is a separate git repo, owned by Red Bear,
|
||||
git-tracked, rebase-friendly, and never touched by the build system's source-regeneration step.
|
||||
It survives every `make clean`, every `make distclean`, every `provision-release.sh`, and every
|
||||
upstream `git pull` we ever run.
|
||||
|
||||
### The 12 Red Bear forks already in place (verified 2026-06-09)
|
||||
|
||||
| # | Fork | Path | Why a fork |
|
||||
|---|------|------|------------|
|
||||
| 1 | `base` | `local/sources/base/` | Red Bear userspace drivers fork — acpid, pcid, inputd, ps2d, xhcid migrations |
|
||||
| 2 | `bootloader` | `local/sources/bootloader/` | UEFI bootloader fork — UEFI alloc fix, branding, GPT offset |
|
||||
| 3 | `installer` | `local/sources/installer/` | Installer fork — ext4 + GRUB support |
|
||||
| 4 | `kernel` | `local/sources/kernel/` | Microkernel fork — ACPI, x2APIC, MSI/MSI-X, scheduling, branding |
|
||||
| 5 | `libdrm` | `local/sources/libdrm/` | DRM/KMS userspace library — ioctl bridge, PCI info, device enumeration |
|
||||
| 6 | `mesa` | `local/sources/mesa/` | Mesa 3D graphics library — virgl disk cache, GBM dumb prime export, hardware driver work |
|
||||
| 7 | `pipewire` | `local/sources/pipewire/` | PipeWire audio server — Redox compat shims |
|
||||
| 8 | `redox-drm` | `local/sources/redox-drm/` | DRM/KMS scheme daemon — Intel + AMD display drivers, MSI/MSI-X fallback, DISABLE_ACCEL |
|
||||
| 9 | `redoxfs` | `local/sources/redoxfs/` | RedoxFS — primary filesystem, Red Bear schema/improvements |
|
||||
| 10 | `relibc` | `local/sources/relibc/` | C library — eventfd, signalfd, timerfd, waitid, SysV IPC, credential syscalls |
|
||||
| 11 | `userutils` | `local/sources/userutils/` | Userland utilities — login/getty/login helpers, prompt/welcome text |
|
||||
| 12 | `wireplumber` | `local/sources/wireplumber/` | WirePlumber session manager — PipeWire policy |
|
||||
|
||||
**Verification command:**
|
||||
|
||||
```bash
|
||||
ls -1 /home/kellito/Builds/RedBear-OS/local/sources/
|
||||
# Expected (12 entries):
|
||||
# base bootloader installer kernel libdrm mesa
|
||||
# pipewire redox-drm redoxfs relibc userutils wireplumber
|
||||
```
|
||||
|
||||
### The exception: in-tree Red Bear components
|
||||
|
||||
`kernel`, `relibc`, `base`, `installer`, and `bootloader` are listed in **both** the
|
||||
"in-tree Red Bear components" and the "forks at `local/sources/`" tables above. That is
|
||||
intentional. These components are forked at `local/sources/<component>/` (Rule 2 — big
|
||||
project, durability matters), but the mainline `recipes/<category>/<component>/recipe.toml`
|
||||
**points at the fork** (not the other way around — no symlink, no overlay, no patch
|
||||
file). The fork IS the source of truth; the recipe just builds it.
|
||||
|
||||
For **small Red Bear-initiated new packages** (cub, redbear-info, redbear-netctl,
|
||||
redbear-sessiond, redbear-authd, …) the rule is Rule 1: a `local/recipes/<category>/<name>/`
|
||||
fork replaces the upstream recipe entirely. No symlinks, no overlay layer.
|
||||
|
||||
For **upstream Redox system internals that we do not modify** (core/pkgar, core/ion,
|
||||
core/dash, core/coreutils, gui/orbital, …) we pull from upstream at a pinned revision
|
||||
and the build is fine. The Redox ABI must not diverge.
|
||||
|
||||
### Concrete walk-through: direct edit vs. fork
|
||||
|
||||
**Scenario:** You want to add `-Dplatforms=wayland` to the Mesa build to enable the
|
||||
Wayland EGL platform, which is the prerequisite for KWin to find an EGL/GBM/GLES2 surface.
|
||||
|
||||
#### Direct edit (WRONG — Rule 1 anti-pattern)
|
||||
|
||||
1. Edit `recipes/libs/mesa/recipe.toml` to add `-Dplatforms=wayland` to the meson args.
|
||||
2. Run `repo cook recipes/libs/mesa`. The build succeeds. Mesa now exposes Wayland EGL.
|
||||
3. Two days later, upstream Mesa 25.0 is released.
|
||||
4. You run `make distclean` (or `make clean` or `repo fetch recipes/libs/mesa`).
|
||||
5. The cookbook refetches Mesa from the pinned git URL. The `recipe.toml` is overwritten
|
||||
with whatever is at the new rev. **Your `-Dplatforms=wayland` change may be wiped,
|
||||
may be preserved, or may collide with a new upstream flag. Outcome is non-deterministic.**
|
||||
6. If the recipe `rev` is bumped, the source tree is also refetched. Your hand-edited
|
||||
Meson build files inside `recipes/libs/mesa/source/` are GONE.
|
||||
7. If you try to recover by re-applying, you are now maintaining a patch series on top
|
||||
of multi-million-line upstream Mesa. Every upstream bump is a `git apply` rebase.
|
||||
8. **Your Red Bear patches are LOST or have become unmaintainable.**
|
||||
|
||||
#### Fork (CORRECT — Rule 2, what we actually do)
|
||||
|
||||
1. The Mesa fork is already at `local/sources/mesa/`, on branch `0.2.3`, with our existing
|
||||
EGL Wayland commits. (See `local/sources/mesa/` for the current state.)
|
||||
2. Add a Red Bear commit on `local/sources/mesa/0.2.3`:
|
||||
```bash
|
||||
cd local/sources/mesa
|
||||
# Edit meson.build, meson_options.txt to add Wayland EGL platform support
|
||||
git add meson.build meson_options.txt
|
||||
git commit -m "mesa: enable Wayland EGL platform (-Dplatforms=wayland) for KWin"
|
||||
```
|
||||
3. The mainline `recipes/libs/mesa/recipe.toml` already points at the fork:
|
||||
```toml
|
||||
[source]
|
||||
path = "../../../local/sources/mesa"
|
||||
```
|
||||
No change needed there.
|
||||
4. Run `./local/scripts/build-redbear.sh redbear-full`. Mesa builds with Wayland EGL.
|
||||
The build artifact lands in `repo/x86_64-unknown-redox/mesa.pkgar` + `mesa.toml`.
|
||||
5. Two days later, upstream Mesa 25.0 is released. We want to pull it.
|
||||
6. Bump the upstream reference in the fork:
|
||||
```bash
|
||||
cd local/sources/mesa
|
||||
git remote add upstream https://gitlab.freedesktop.org/mesa/mesa.git # one-time
|
||||
git fetch upstream
|
||||
git checkout 0.2.3
|
||||
git rebase upstream/25.0 # rebase OUR patches on top of new upstream
|
||||
# Resolve the (rare, well-localized) conflicts in meson.build, meson_options.txt
|
||||
git push origin 0.2.3
|
||||
```
|
||||
7. The mainline recipe's `rev` is updated in `local/recipes/libs/mesa/recipe.toml` (or
|
||||
in the upstream mainline recipe that points at the fork), and the build proceeds.
|
||||
8. **Our Red Bear patches SURVIVE — they live on the `0.2.3` branch of our fork, are
|
||||
rebased forward at our discretion, and are visible in `git log` of the fork.**
|
||||
|
||||
### Rule-of-thumb decision matrix
|
||||
|
||||
| Is the component … | Then … |
|
||||
|---|---|
|
||||
| An in-tree Red Bear core (kernel, relibc, base, installer, bootloader) | **Rule 1 + Rule 2 hybrid** — fork at `local/sources/<component>/` is the source of truth; mainline recipe points at the fork. No patches, no symlinks. |
|
||||
| A small Red Bear-initiated new package (cub, redbear-info, redbear-netctl, redbear-sessiond, redbear-authd, …) | **Rule 1** — `local/recipes/<category>/<name>/` fork replaces the upstream recipe. No symlinks, no overlay. |
|
||||
| A big external project (mesa, wayland, qt, KF6, KWin, SDDM, llvm, libdrm, redox-drm, libepoxy, pipewire, wireplumber, …) | **Rule 2** — Red Bear fork at `local/sources/<component>/`. Mainline recipe points at the fork via `path = "../../../local/sources/<component>"` or `git = "https://gitea.redbearos.org/redbear/<component>.git"`. |
|
||||
| An upstream Redox system-internal that we do not modify (core/pkgar, core/ion, core/dash, core/coreutils, gui/orbital, …) | No fork. Pull from upstream at pinned revision. The Redox ABI must not diverge. |
|
||||
| A pure Cargo dep that we do not fork (redox_syscall, libredox, redox-scheme, pkgar, …) | Pulled via Cargo from upstream crates.io. No recipe. |
|
||||
|
||||
The default for anything multi-thousand-line external is **Rule 2 (fork)**.
|
||||
The default for anything Red Bear-initiated is **Rule 1 (local recipe that replaces upstream)**.
|
||||
In-tree Red Bear core components live at `local/sources/<component>/` and the mainline
|
||||
recipe points at them.
|
||||
|
||||
### Cross-references
|
||||
|
||||
- `local/AGENTS.md` — "NO OVERLAY-STYLE PATCHES — SCOPED POLICY (AMENDED 2026)" sections,
|
||||
Rule 1 (in-tree Red Bear components) and Rule 2 (big external projects).
|
||||
- `local/AGENTS.md` — "SOURCE-OF-TRUTH RULE" section, two-layer architecture
|
||||
(`recipes/*/source/` is ephemeral; `local/sources/`, `local/recipes/`, `local/docs/`,
|
||||
tracked configs are durable).
|
||||
- `local/AGENTS.md` — "STUB AND WORKAROUND POLICY — ZERO TOLERANCE" for what to do when
|
||||
a fork's build breaks (fix it in the fork, never disable features in the consumer).
|
||||
- `local/AGENTS.md` — "DESIGN PRINCIPLE" and "RELEASE MODEL (FORK — NOT OVERLAY)" for
|
||||
the upstream-baseline + fork-on-top architecture.
|
||||
- `local/AGENTS.md` — "STRUCTURE" for the full directory map.
|
||||
- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — canonical desktop path plan that consumes
|
||||
the mesa, wayland, qt, KF6, KWin, SDDM, libdrm, redox-drm, libepoxy forks.
|
||||
|
||||
### Audit commands
|
||||
|
||||
Verify no overlay state has crept back into the tree:
|
||||
|
||||
```bash
|
||||
# (a) Every recipe must have exactly one source — no duplicate recipe.toml,
|
||||
# no symlinks hiding the fork.
|
||||
find recipes/ -name "recipe.toml" -path "*/local/*" -o -lname "*/local/*" 2>/dev/null
|
||||
|
||||
# (b) Every Red Bear fork at local/sources/ must be a git repo.
|
||||
for d in local/sources/*/; do
|
||||
[ -d "$d/.git" ] || echo "MISSING .git: $d"
|
||||
done
|
||||
|
||||
# (c) Every mainline recipe that claims a fork must point at the right path.
|
||||
grep -r "local/sources/" recipes/ --include="recipe.toml" | head -50
|
||||
```
|
||||
|
||||
If any of these checks return unexpected output, the build is in an overlay state. Fix by
|
||||
forking the recipe properly per `local/AGENTS.md` Rule 1 or Rule 2.
|
||||
|
||||
**Decision date:** 2026-06-09
|
||||
**Decision authority:** `local/AGENTS.md` "NO OVERLAY-STYLE PATCHES — SCOPED POLICY (AMENDED 2026)"
|
||||
**Verification status:** 12 of 12 expected Red Bear forks present at `local/sources/`.
|
||||
**Out-of-scope:** This section does not change the per-component build flags, the
|
||||
`redbear-full` package set, or the relibc POSIX surface — those are tracked in
|
||||
`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`, `local/docs/STUBS-FIX-PROGRESS.md` Phase tables,
|
||||
and `local/recipes/` per-component recipes respectively.
|
||||
|
||||
+1
-1
Submodule local/sources/base updated: 0df7977d45...cffacf5918
Reference in New Issue
Block a user