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 <comp>/
  - 97 legacy-superseded-2026-07-12/<comp>/ (Round 2-6 audits)
  - 62 legacy-absorbed-2026-07-12/<comp>/ (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
This commit is contained in:
2026-07-12 10:37:00 +03:00
parent 4a440131d9
commit 34a1506534
+109
View File
@@ -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
├── <comp>/ # ACTIVE patches (121)
│ ├── <fork>/ # base, kernel, relibc, ...
│ │ ├── P3-*.patch # applied by cookbook
│ │ └── redox.patch # legacy all-in-one (gitignored)
│ ├── <fork>/absorbed/ # historical snapshots
│ │ └── P3-*.patch # PATCHES BEFORE they were committed
│ │ # to fork via mega-absorption. Recoverable.
│ └── <fork>/.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/<comp>/<patch>.patch \
local/patches/<comp>/
# Optionally try applying it (will probably be a no-op for INTEGRATED,
# may fail for SUPERSEDED)
cd local/sources/<comp>
git apply --check -N -p1 < ../../local/patches/<comp>/<patch>.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/<comp>/`. 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).