From aa9d14a90e5bd20ff9a98c11bdd474c035ee9b31 Mon Sep 17 00:00:00 2001 From: Admin Pupkin Date: Fri, 29 May 2026 21:50:28 +0300 Subject: [PATCH] docs: update AGENTS.md and PATCH-GOVERNANCE.md 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 --- AGENTS.md | 113 ++++++++++++++++++++++++++++++++- local/docs/PATCH-GOVERNANCE.md | 42 +++++++++++- 2 files changed, 150 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ea6aa1fe06..eb279daa14 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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-.patch + +# 4. Create symlink and wire into recipe.toml +cd ../../../recipes/core/base +ln -s ../../../local/patches/base/P-.patch P-.patch +# Add "P-.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 diff --git a/local/docs/PATCH-GOVERNANCE.md b/local/docs/PATCH-GOVERNANCE.md index ca5fcc5ebc..9d35636782 100644 --- a/local/docs/PATCH-GOVERNANCE.md +++ b/local/docs/PATCH-GOVERNANCE.md @@ -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-.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. |