From 34a150653466cfbc26fa4a1fda3b730137fad838 Mon Sep 17 00:00:00 2001 From: vasilito Date: Sun, 12 Jul 2026 10:37:00 +0300 Subject: [PATCH] phase 6.3: add local/patches/README.md explaining archive structure Round 7 baseline snapshot revealed the local/patches/ tree has grown organically through Rounds 1-6: - 121 active patches under / - 97 legacy-superseded-2026-07-12// (Round 2-6 audits) - 62 legacy-absorbed-2026-07-12// (Round 2-3 audits) - 0 legacy-recipe-patches/ (deleted in Round 1.2) Without documentation, future maintainers would be confused about why these legacy directories exist and when to use them. This README explains the distinction between: - 'superseded' (content NOT in fork, re-applying causes work) - 'absorbed' (content IS in fork, re-applying is a no-op) The README also documents: - Layout diagram - Recovery procedure - Round 7 snapshot (280 total cataloged patches) - Tooling references - How new orphans should be handled --- local/patches/README.md | 109 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 local/patches/README.md diff --git a/local/patches/README.md b/local/patches/README.md new file mode 100644 index 0000000000..27dfb6595a --- /dev/null +++ b/local/patches/README.md @@ -0,0 +1,109 @@ +# local/patches/ — patch archive structure + +**Last updated:** 2026-07-12 (Round 7) +**Status:** Build system at 100% patch preservation. 121 active +patches + 159 archived = 280 total cataloged patches. + +## Layout + +``` +local/patches/ +├── README.md # this file +├── / # ACTIVE patches (121) +│ ├── / # base, kernel, relibc, ... +│ │ ├── P3-*.patch # applied by cookbook +│ │ └── redox.patch # legacy all-in-one (gitignored) +│ ├── /absorbed/ # historical snapshots +│ │ └── P3-*.patch # PATCHES BEFORE they were committed +│ │ # to fork via mega-absorption. Recoverable. +│ └── /.gitignore'd # cargo metadata etc +├── legacy-superseded-2026-07-12/ # Round 2-6 archive (97) +│ ├── README + SUPERSEDED.md # per-component audit log +│ ├── base/, kernel/, relibc/, redoxfs/, userutils/ +│ └── P3-*.patch # classified-SUPERSEDED +└── legacy-absorbed-2026-07-12/ # Round 2-3 archive (62) + ├── README + SUPERSEDED.md # per-component audit log + ├── base/, kernel/, relibc/, userutils/ + └── P3-*.patch # classified-INTEGRATED +``` + +## What's an "absorbed" patch? + +A patch is moved to `legacy-absorbed-2026-07-12/` when Round 2-3's +supersession classifier determined that **the same fix is already +committed to the fork's HEAD** under a different commit subject. The +.patch file is preserved as historical documentation but is no longer +applied during build. This is **operator-supersession** under AGENTS.md +"Upstream-first rule for fast-moving components". + +The patch's content IS in the fork. Re-applying would either: +- Be a no-op (`patch -N` for already-applied) — safe +- Cause a real conflict (if fork content has since evolved past the + patch's intent) — operator decision needed + +## What's a "superseded" patch? + +A patch is moved to `legacy-superseded-2026-07-12/` when its content +is no longer needed at all — either: +- Upstream Redox's newer tag already provides equivalent functionality + (canonical "upstream preferred" path) +- The fork's file structure has been rebased past the patch's + expectations (file-restructured) +- The operator cleaned up the corresponding code as part of a + refactor (operator-superseded) + +The patch's content is NOT in the fork. Re-applying would create +unintended work. Recovery: rebase fork onto newer upstream or accept +the operator's refactor. + +## How to recover a patch + +```bash +# Move patch back to active location +cp local/patches/legacy-superseded-2026-07-12//.patch \ + local/patches// + +# Optionally try applying it (will probably be a no-op for INTEGRATED, +# may fail for SUPERSEDED) +cd local/sources/ +git apply --check -N -p1 < ../../local/patches//.patch +``` + +## Tooling + +The patch audit tool runs as part of `pre-push-checks.sh`: + +```bash +./local/scripts/pre-push-checks.sh +``` + +The 5 checks are: sync-versions, verify-fork-versions, +verify-patch-content, verify-collision-detection, and the collision +selftest. All must pass for the pre-push hook to allow a `git push`. + +For a full operator-decision guide on what to do with new orphans, +see `local/docs/PATCH-PRESERVATION-AUDIT-2026-07-12.md` (the "Out-of- +scope" section tracks the current Round 5+6 forward work). + +## Round 7 snapshot + +| Directory | Count | Source | +|-----------|-------|--------| +| `*/` (active) | 121 | operator's working fork state | +| `legacy-superseded-2026-07-12/` | 97 | Round 2-6 SUPERSEDED audits | +| `legacy-absorbed-2026-07-12/` | 62 | Round 2-3 INTEGRATED audits | +| `legacy-recipe-patches/` | 0 | (deleted in Round 1.2; not a separate dir anymore) | +| **Total cataloged** | **280** | | + +## Notes + +- Each legacy/ directory has its own SUPERSEDED.md audit log with + per-component tables of what was archived, when, and why. +- The `absorbed/` subdir under each active component (`base/absorbed/`, + `relibc/absorbed/`) was removed in Round 3.0; its content was + consolidated into `legacy-absorbed-2026-07-12//`. The `absorbed/` + under each component's recipe was Round 2's experimental split. +- New orphans detected by `verify-patch-content.sh` are NOT + automatically archived — that's an operator decision. See + `local/scripts/verify-patch-content.sh --help` (no current + options; future work: add a `--auto-archive` mode).