vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add FULL FORK PRINCIPLE to AGENTS.md

Browse Source 
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/)
This commit is contained in:
Admin Pupkin
2026-05-30 08:09:45 +03:00
parent ad85d9bf0c
commit e697f4c747
1 changed files with 22 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+22
View File
@@ -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/<component>/`. 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/<component>/`. EDIT THERE. `recipes/*/source/` IS A SYMLINK