From e697f4c747dd12dac4bf09edf5dde8ae3aecc77f Mon Sep 17 00:00:00 2001 From: Admin Pupkin Date: Sat, 30 May 2026 08:09:45 +0300 Subject: [PATCH] docs: add FULL FORK PRINCIPLE to AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the fundamental architectural rule: Red Bear OS is a FULL FORK. We do not depend on Redox. We reuse Redox code only when needed — and when we do, we fork it into our own repos. Key rules: - Own your dependencies (local/sources/ or local/recipes/) - No waiting for upstream (fix in our fork) - Frozen snapshots only (never auto-pull) - Upstream gitlab URLs are temporary (91 remaining, to be forked) - Our code, our fixes (fix forward when APIs break) - Durable state (commit to local/sources/) --- AGENTS.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 6f02ea8310..6cde48835e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,28 @@ to the appropriate fork repo. Durable Red Bear state belongs in `local/sources/` The current baseline is **Red Bear OS 0.1.0** (Redox snapshot at build-system commit `f55acba68`). +## FULL FORK PRINCIPLE + +**Red Bear OS is a FULL FORK. We do not depend on Redox. We reuse Redox code only +when needed — and when we do, we fork it into our own repos.** + +This means: + +| Rule | Explanation | +|---|---| +| **Own your dependencies** | Every crate and library Red Bear uses must have its source accessible in `local/sources/` or `local/recipes/`. No depending on upstream crates that we cannot fix ourselves. | +| **No waiting for upstream** | If a dependency breaks, we fix it in our fork. We do not file issues and wait. | +| **Frozen snapshots only** | Upstream Redox is a reference, not a live dependency. We baseline on frozen snapshots and never auto-pull. | +| **Upstream gitlab URLs are temporary** | Any recipe pointing at `gitlab.redox-os.org` (91 currently) must eventually be forked to `local/sources/` or pinned to a frozen archive. Exceptions: unmodified upstream packages with pinned revisions. | +| **Our code, our fixes** | When crate APIs change (e.g., `libredox 0.1.0` → `0.1.17` broke `call_ro`/`call_wo` signatures), we update OUR fork's code. We don't revert our code to match old APIs — we fix forward. | +| **Durable state** | All source modifications are committed to `local/sources//`. No edits in `recipes/*/source/` survive a rebuild. | + +**Concretely:** +- `local/recipes/drivers/redox-driver-sys/` is OUR fork. We fix compilation errors there. +- `local/sources/kernel/` is OUR kernel. We don't pull from `gitlab.redox-os.org/redox-os/kernel`. +- If a Cargo dependency breaks, we fork the dependency crate to `local/sources/` and pin our Cargo.toml to our fork. +- The Linux kernel in `local/reference/` is read-only reference — never a dependency. + ## BUILD SYSTEM DURABILITY — THE CARDINAL RULE **SOURCE LIVES IN `local/sources//`. EDIT THERE. `recipes/*/source/` IS A SYMLINK