From b4b41fd78ec50bbf47a562063db5ccca4b303bed Mon Sep 17 00:00:00 2001 From: Admin Pupkin Date: Fri, 29 May 2026 22:54:38 +0300 Subject: [PATCH] docs: rewrite local/AGENTS.md for source ownership model --- local/AGENTS.md | 62 +++++++++++++++++++++++-------------------------- 1 file changed, 29 insertions(+), 33 deletions(-) diff --git a/local/AGENTS.md b/local/AGENTS.md index 36a4aef586..b37f2e937c 100644 --- a/local/AGENTS.md +++ b/local/AGENTS.md @@ -3,22 +3,22 @@ ## INTERNAL-FIRST POLICY When building packages, resolving dependencies, or choosing between implementations, -**always prefer internal Red Bear recipes and patched sources** over upstream or +**always prefer internal Red Bear source forks and recipes** over upstream or third-party alternatives. This applies at every decision point: | Decision | Always prefer | |----------|--------------| | Recipe location | `local/recipes/` over `recipes/` (upstream) | -| Patch source | `local/patches/` over in-tree edits or ad-hoc sed | -| Source tarball | Patched archive in `sources/redbear-0.1.0/tarballs/` over re-download | +| Source code | `local/sources/` (git forks, directly editable) over upstream clones | +| Source archive | Frozen archive in `sources/redbear-0.1.0/tarballs/` over re-download | | Implementation | Red Bear Rust implementation over upstream C port | | Config | `config/redbear-*.toml` over mainline `config/*.toml` | | Scripts | `local/scripts/` over ad-hoc shell commands | **Concretely:** if `local/recipes///` exists and is symlinked into the recipe tree, that is the authoritative recipe — never fall back to the upstream -`recipes/` version. If a local recipe has a `redox.patch`, that patch is the -maintained Red Bear delta — never work around it by editing the source tree directly. +`recipes/` version. Source changes go as git commits in `local/sources//`, +never as ad-hoc edits to recipe source trees. **Rationale:** the local overlay is the durable, version-controlled, release-safe layer. Upstream recipes are disposable and may be overwritten by `make distclean` or release @@ -48,7 +48,7 @@ updates (`git pull` on the build system repo), this directory is untouched. ## STUB AND WORKAROUND POLICY — ZERO TOLERANCE **Red Bear OS has zero tolerance for stubs, workarounds, `#ifdef`-guarded no-ops, fake headers, -shell-script patches, sed/awk hacks, `LD_PRELOAD` tricks, rename-to-.disabled wrappers, or any +sed/awk hacks, `LD_PRELOAD` tricks, rename-to-.disabled wrappers, or any other "make it compile" shortcut.** If something doesn't build because of a missing implementation, the ONLY acceptable response is @@ -78,12 +78,12 @@ files, Wayland protocol stubs, D-Bus service stubs, and any other layer of the s ### Every Build Lands in the Repo -Every successful `repo cook ` MUST produce two durable artifacts: +Every successful `repo cook ` MUST produce durable artifacts: 1. **Package in the repo**: `repo/x86_64-unknown-redox/.pkgar` + `.toml` -2. **Patched source form**: All source modifications mirrored to `local/patches//` +2. **Committed source**: All source modifications committed in the appropriate `local/sources//` git repo -A build is **not complete** until both exist. Verify after every cook: +A build is **not complete** until the repo artifacts exist. Verify after every cook: ```bash ./target/release/repo find # Must find the package @@ -92,8 +92,7 @@ ls repo/x86_64-unknown-redox/.pkgar # Archive must exist ``` If a package was built but the repo artifacts are missing, the build did not complete. -If source patches exist only in `recipes/*/source/` but not in `local/patches/`, -the patches are not durable (see Source-of-Truth Rule below). +If source changes were made but not committed to `local/sources//`, commit them there. ### Cascade Rebuild Rule @@ -237,7 +236,7 @@ tree alone to preserve Red Bear work. These paths are our actual long-term source of truth: -- `local/patches/` — all durable changes to upstream-owned source trees +- `local/sources/` — Red Bear source forks (git repos, directly editable) - `local/recipes/` — Red Bear recipe release fork and new packages - `local/docs/` — Red Bear planning, validation, and integration documentation - tracked Red Bear configs such as `config/redbear-*.toml` @@ -255,12 +254,9 @@ prefer the upstream solution whenever upstream already solves the same problem. That means: -- if our local patch solves a gap that upstream still has, keep the patch carrier -- if upstream lands an equivalent or better solution, prefer upstream and shrink or drop our local patch -- do not keep a Red Bear patch just because it existed first; keep it only while it still provides unique value - -For relibc specifically, patch carriers should be treated as **temporary compatibility release fork**, -not a permanent fork strategy. +- if our source fork has a fix that upstream still needs, keep it in the fork +- if upstream lands an equivalent or better solution, prefer upstream and port our additional changes on top +- do not keep Red Bear-specific code just because it existed first; keep it only while it still provides unique value When upstream Redox already provides a package, crate, or subsystem for functionality that also exists in Red Bear local code, prefer the upstream Redox version by default unless the Red Bear @@ -275,15 +271,15 @@ For quirks and driver support specifically: - if duplication is temporarily unavoidable, treat it as convergence work to remove, not as a permanent design. -### Daily-upstream-safe workflow +### Daily workflow -For any change to upstream-owned source: +For any change to Red Bear-owned source: -1. make the minimal working change in the live source tree if needed for validation -2. prove it builds/tests against the real recipe -3. mirror that delta into `local/patches//...` -4. update `local/docs/...` so the provisioning story is explicit -5. assume the live upstream source tree may be thrown away and recreated at any time +1. edit the source in `local/sources//` +2. build: `repo cook ` +3. test: `make qemu` +4. commit: `git -C local/sources// commit` +5. push: `git -C local/sources// push` The success criterion is therefore: @@ -336,12 +332,12 @@ redox-master/ ← git pull updates mainline Redox │ │ │ ├── redbear-dbus-services ← D-Bus .service activation files + XML policies │ │ ├── wayland/ ← Wayland compositor (Phase 2) │ │ └── kde/ ← KDE Plasma (Phases 3–4) -│ ├── patches/ -│ │ ├── kernel/ ← Kernel patches (ACPI, x2APIC) -│ │ ├── base/ ← Base patches (acpid fixes, power methods, pcid /config endpoint) -│ │ ├── relibc/ ← relibc compatibility release fork still needed beyond upstream (eventfd, signalfd, timerfd, waitid, SysV IPC) -│ │ ├── bootloader/ ← Bootloader patches -│ │ └── installer/ ← Installer patches (ext4 filesystem support + GRUB bootloader) +│ ├── sources/ ← Red Bear source forks (git repos, directly editable) +│ │ ├── kernel/ ← Red Bear's kernel fork +│ │ ├── relibc/ ← Red Bear's C library fork +│ │ ├── base/ ← Red Bear's userspace drivers fork +│ │ ├── bootloader/← Red Bear's bootloader fork +│ │ └── installer/ ← Red Bear's installer fork │ ├── Assets/ ← Branding assets (icon, loading background) │ │ └── images/ ← Red Bear OS icon (1254x1254) + loading bg (1536x1024) │ ├── firmware/ ← GPU firmware blobs (gitignored, fetched) @@ -520,7 +516,7 @@ When mainline updates affect our work: | Mesa | OpenGL/Vulkan backend changes | `recipes/libs/mesa/` | | Build system | Makefile/config changes | `mk/`, `src/` | | rsext4 | ext4 crate API changes | `local/recipes/core/ext4d/source/` Cargo.toml | -| Installer | ext4 dispatch, filesystem selection, GRUB bootloader | `local/patches/installer/redox.patch` | +| Installer | ext4 dispatch, filesystem selection, GRUB bootloader | `local/sources/installer/` (git fork) | | Quirks | New Linux quirk entries to port | `local/recipes/drivers/redox-driver-sys/source/src/quirks/` | ## PLANNING NOTES @@ -649,7 +645,7 @@ recipes/core/ext4d → local/recipes/core/ext4d - `libredox = "0.1.13"` — High-level Redox syscalls (open, read, write, fstat) - `redox-path = "0.3.0"` — Redox path utilities -### Installer ext4 + GRUB Integration (`local/patches/installer/redox.patch`) +### Installer ext4 + GRUB Integration The mainline installer is patched to support ext4 as an install target filesystem and GRUB as an alternative boot manager: