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

docs: update AGENTS.md and PATCH-GOVERNANCE.md

Browse Source 
AGENTS.md: updated session progress, coretempd/login fix notes, Intel plan references. PATCH-GOVERNANCE.md: added mega-patch discipline section and P-patch workflow documentation.

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
Admin Pupkin
2026-05-29 21:50:28 +03:00
parent 44bcf2b75a
commit aa9d14a90e
2 changed files with 150 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+110 -3
View File
@@ -1,6 +1,6 @@
# RED BEAR OS BUILD SYSTEM — PROJECT KNOWLEDGE BASE
**Generated:** 2026-04-12 (P1/P2 complete)
**Generated:** 2026-04-12 (P1/P2 complete) · Updated: 2026-05-29 (mega-patch discipline)
**Toolchain:** Rust nightly-2025-10-03 (edition 2024)
**Architecture:** Microkernel OS in Rust, ~38k files, ~294k LoC Rust
**Target Hardware**: AMD64 bare metal, with AMD and Intel machines treated as equal-priority Red Bear OS targets
@@ -812,10 +812,116 @@ patches must be respected:
When reordering patches: remove the source tree, re-fetch, and rebuild to verify.
### MEGA-PATCH + INDIVIDUAL PATCH DISCIPLINE (CRITICAL)
**This is the single most common source of build failures in Red Bear OS.**
Violating these rules causes patches to silently drift, overlap, or conflict —
wasting hours of debugging time.
#### The Two-Layer Architecture
Each patched component (base, kernel, relibc) uses two patch layers:
1. **The mega-patch** (`redox.patch`) — a single consolidated `git diff` of the
entire source tree against upstream. Applied first. This is the **frozen baseline**
of all Red Bear work up to a known date.
2. **Individual P-patches** (`P10-*.patch`, `P11-*.patch`, etc.) — granular,
single-purpose patches for new work done AFTER the mega-patch was generated.
Applied after the mega-patch, in listed order.
The `recipe.toml` patches list looks like:
```toml
patches = [
"redox.patch", # Layer 1: frozen baseline
"P10-rootfs-uuid-search-no-block.patch", # Layer 2: new work on top
"P11-init-noise-reduction.patch", # Layer 2: new work on top
]
```
#### The Discipline (MANDATORY)
| Rule | Why | What happens if violated |
|------|-----|--------------------------|
| **NEVER regenerate `redox.patch` from a source tree that includes P-patches** | The mega-patch absorbs P-patch changes, making P-patches redundant. They then fail to apply ("Reversed or previously applied") on the next clean build. | P-patches conflict with their own changes inside the mega-patch. Build fails. |
| **New work always goes as P-patches AFTER the mega-patch** | Keeps the mega-patch frozen. Each P-patch is a small, reviewable delta. | Mixing changes into the mega-patch makes it a monolith with no logical structure. |
| **To regenerate `redox.patch`, first fold all P-patches into it, then remove them from `recipe.toml`** | Consolidation pass must be atomic — absorb and remove in one step. | Orphan P-patches in `recipe.toml` reference changes already in the mega-patch. |
| **P-patches MUST apply cleanly on top of the mega-patch-only state** | The build system applies patches sequentially: upstream → mega-patch → P-patches. | Build fails on clean fetch. |
| **Validate with `repo validate-patches` after ANY patch change** | Catches drift before it reaches the build. | Drift silently accumulates until the next clean build explodes. |
#### How to Make a New Change (Correct Workflow)
```bash
# 1. Source tree already has mega-patch + existing P-patches applied (working tree)
cd recipes/core/base/source
# 2. Make your edit
vim init/src/main.rs
# 3. Generate the patch against the current git HEAD (upstream rev)
git diff -U0 -w -- init/src/main.rs > ../../../local/patches/base/P<next>-<desc>.patch
# 4. Create symlink and wire into recipe.toml
cd ../../../recipes/core/base
ln -s ../../../local/patches/base/P<next>-<desc>.patch P<next>-<desc>.patch
# Add "P<next>-<desc>.patch" to patches list in recipe.toml
# 5. Validate and rebuild
cd ../../..
./target/release/repo validate-patches base
CI=1 ./target/release/repo cook base-initfs
```
#### How to Consolidate (Periodic Maintenance)
When P-patches accumulate and the mega-patch should absorb them:
```bash
# 1. Source tree has mega-patch + all P-patches applied
cd recipes/core/base/source
# 2. Generate NEW mega-patch from full diff
git diff -U0 -w > ../../../local/patches/base/redox.patch
# 3. Remove ALL P-patches from recipe.toml patches list
# Keep P-patch FILES in local/patches/base/ for history — just remove from recipe.toml
# 4. Validate
./target/release/repo validate-patches base
# 5. Rebuild
CI=1 ./target/release/repo cook base-initfs
```
#### How NOT to Break Things
| Action | Correct | WRONG |
|--------|---------|-------|
| Add new feature | Create P-patch, add after mega-patch in recipe.toml | Regenerate mega-patch from tree that includes P-patches |
| Fix a bug | Create P-patch | Edit mega-patch directly |
| Consolidate | Regenerate mega-patch, remove ALL P-patches from recipe.toml | Regenerate mega-patch but leave P-patches in recipe.toml |
| Update upstream | Provision new release, rebase mega-patch | Cherry-pick upstream commits into source tree |
#### Root Cause of Past Failures
The pattern that has recurred multiple times:
1. Mega-patch generated at time T
2. P-patches added at time T+1, T+2, etc.
3. Someone regenerates mega-patch from source tree at T+3 (which includes P-patch changes)
4. Mega-patch now contains P-patch changes
5. P-patches still in `recipe.toml` try to re-apply their changes → conflicts
6. Build fails with "Reversed or previously applied" and hunk failures
7. Hours spent debugging why "patches that used to work" now fail
**The fix is always the same**: either (a) remove the absorbed P-patches from `recipe.toml`,
or (b) regenerate the mega-patch from a tree WITHOUT P-patch changes. Option (a) is faster.
### Large Patch Files (redox.patch)
`local/patches/base/redox.patch` (consolidated mega-patch) is stored as 90 MB
chunks under `local/patches/base/redox-patch-chunks/` and reassembled by:
`local/patches/base/redox.patch` (consolidated mega-patch) is currently ~544K.
If it grows beyond a manageable size, it can be chunked under
`local/patches/base/redox-patch-chunks/` and reassembled by:
```bash
local/patches/base/reassemble-redox-patch.sh
```
@@ -830,6 +936,7 @@ Critical rules:
- **Source trees are disposable** — `repo clean`/`distclean` destroy them
- **All source changes must be patches** in `local/patches/`
- **Commit patch files and recipe.toml changes** before session end
- **NEVER regenerate mega-patch from a tree that includes P-patches** — see MEGA-PATCH DISCIPLINE above
### Build Validation
local/docs/PATCH-GOVERNANCE.md
+40 -2
View File
@@ -16,6 +16,44 @@ The code was recovered from git history, but this must never happen again.
## Rules
### 0. MEGA-PATCH + P-PATCH DISCIPLINE (HIGHEST PRIORITY)
Each patched component (base, kernel, relibc) uses a two-layer patch model:
- **`redox.patch`** (the mega-patch) — frozen baseline of all Red Bear work. Applied first.
- **`P<N>-<desc>.patch`** (individual patches) — new work done AFTER the mega-patch. Applied after.
**The single rule that prevents the most build failures:**
> **NEVER regenerate `redox.patch` from a source tree that includes P-patch changes.**
If the source tree has P-patches applied (visible in `git status --short` or in the recipe.toml
patches list after `redox.patch`), then `git diff` from that tree will absorb the P-patches into
the mega-patch. The P-patches will then fail to apply on the next clean build because their
changes are already in the mega-patch.
**Correct operations:**
| Operation | How |
|-----------|-----|
| Add new change | Create a new P-patch, add it after `redox.patch` in `recipe.toml` |
| Consolidate P-patches into mega-patch | Generate new `redox.patch` from full source tree, then **remove all P-patches from `recipe.toml`** in the same commit |
| Fix a bug in a P-patch | Create a new P-patch that fixes it (or regenerate just that P-patch) |
**Wrong operations (causes build failures):**
| Wrong operation | What breaks |
|-----------------|-------------|
| Regenerate mega-patch from tree with P-patches, leave P-patches in recipe.toml | P-patches try to re-apply changes already in mega-patch → "Reversed or previously applied" |
| Edit mega-patch by hand | Line counts go wrong, hunks fail, impossible to debug |
| Remove P-patches from recipe.toml without folding into mega-patch | Changes are lost entirely |
**Incident log:**
| Date | What happened | Root cause | Fix |
|------|---------------|-----------|-----|
| 2026-05-29 | `validate-patches base` showed mega-patch with 100+ hunk failures, P10/P11/P12 also failing | Mega-patch was regenerated from a source tree that included P-patch changes. Individual P-patches touched same files (`init/src/main.rs`) as mega-patch, causing overlap. | P10/P11/P12 are genuinely new work on top of the mega-patch (not absorbed). The validation failure was from the mega-patch itself being stale for some hunks. Fix: regenerate mega-patch from a clean mega-patch-only tree, then re-apply P-patches. |
### 1. Never remove patches to fix build failures
When a patch fails to apply:
@@ -101,5 +139,5 @@ After ANY change to the patches list or patch files:
| 2026-04-26 | Restored 8 removed patches | Agent deleted them to bypass conflicts; restored all from git HEAD |
| 2026-04-26 | Restored 9 BINS entries | Agent deleted i2cd, gpiod, ucsid, etc. to bypass missing sources |
| 2026-04-26 | Added EXISTING_BINS grep loop | Gracefully handles missing driver source instead of build failure |
| 2026-04-26 | Fixed grep/find variables | `${GREP}` and `${FIND}` are unset in redoxer env; use bare `grep`/`find` |
| 2026-04-26 | Fixed TOML escaping | `\"` in TOML triple-quotes becomes `"` in bash; use `\\\"` for literal `"` |
| 2026-05-29 | Added P12-init-fix-init-debug-import.patch | P11 introduced `init_debug` calls but forgot to import `init_debug` — `use crate::color::{init_error, init_warn, ...}` missing `init_debug`. Build error: `cannot find function init_debug in this scope`. |
| 2026-05-29 | Documented mega-patch discipline (Rule 0) | Recurring patch corruption caused by regenerating mega-patch from trees that include P-patches. Created Rule 0 in PATCH-GOVERNANCE.md and updated AGENTS.md. |