docs: rewrite local/AGENTS.md for source ownership model
This commit is contained in:
+29
-33
@@ -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/<category>/<name>/` 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/<component>/`,
|
||||
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 <package>` MUST produce two durable artifacts:
|
||||
Every successful `repo cook <package>` MUST produce durable artifacts:
|
||||
|
||||
1. **Package in the repo**: `repo/x86_64-unknown-redox/<name>.pkgar` + `<name>.toml`
|
||||
2. **Patched source form**: All source modifications mirrored to `local/patches/<component>/`
|
||||
2. **Committed source**: All source modifications committed in the appropriate `local/sources/<component>/` 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 <package> # Must find the package
|
||||
@@ -92,8 +92,7 @@ ls repo/x86_64-unknown-redox/<package>.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/<component>/`, 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/<component>/...`
|
||||
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/<component>/`
|
||||
2. build: `repo cook <component>`
|
||||
3. test: `make qemu`
|
||||
4. commit: `git -C local/sources/<component>/ commit`
|
||||
5. push: `git -C local/sources/<component>/ 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:
|
||||
|
||||
Reference in New Issue
Block a user