From b814c3397084c27d76dfe007fb2d6ca13e8fa8db Mon Sep 17 00:00:00 2001 From: vasilito Date: Sun, 12 Jul 2026 02:03:55 +0300 Subject: [PATCH] phase 2.3: document orphan-patch supersession decision tree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 2.0 audit discovered that 144 patches in local/patches// were at risk of being silently lost because the build system did not distinguish between: - SUPERSEDED upstream (fork/work covered by upstream or later RB work) - INTEGRATED via different commit (work IS in fork, different SHA) - MISSING-UPSTREAM (work genuinely not in fork — needs reapply) This commit adds an explicit decision tree to AGENTS.md so future operators know: when verify-patch-content.sh reports an orphan, the default action is NOT to immediately reapply. The actual workflow is: 1. Check git log for related commits in the fork 2. Classify the orphan 3. SUPERSEDED/INTEGRATED: move to local/patches/legacy-superseded/ 4. MISSING-UPSTREAM only: try patch -p1 --fuzz=5, else mark for fork rebase (Phase 2.4+) This codifies the Phase 2.0 lessons so future fork-upgrade runs don't repeat the silent-loss pattern that originally caused 144 patches to drift out of sync with their fork commits. --- AGENTS.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 0efcfcfe37..072ccc6f48 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -615,6 +615,52 @@ For quirks and driver support specifically: - if duplication is temporarily unavoidable, treat it as convergence work to remove, not as a permanent design. +### Orphan-Patch Supersession Decision Tree + +When `local/scripts/verify-patch-content.sh` reports that a patch in +`local/patches//` is no longer present in the fork HEAD +(orphan), the default action is **NOT** to reapply the patch. Follow +this decision tree instead (per `local/docs/PATCH-PRESERVATION-AUDIT-2026-07-12.md`): + +``` +1. Run 'git -C local/sources/ log --all --oneline -i --grep ' + where is extracted from the orphan's filename. + +2. ALSO check the target file's git log: + 'git -C local/sources/ log --oneline -- ' + +3. Classify the orphan into one of three buckets: + (a) SUPERSEDED upstream + = Red Bear itself rewrote the function and superseded it + (e.g. acpid/mcfg migration). + Action: MOVE patch to local/patches/legacy-superseded-// + ALSO: if the fork's content covers the same need, no other action. + + (b) INTEGRATED via different commit + = Fork already has commits touching the same file/topic, just + under different commit subjects (typical of mega-absorption + patterns). + Action: MOVE patch to local/patches/legacy-superseded-// + Verification: confirm fork's grep shows new equivalent code. + + (c) MISSING-UPSTREAM (genuine gap) + = Fork has no commits touching the topic AND no upstream alternative. + Action: try `patch -p1 --fuzz=5` (file structure may have drifted). + If still fails: requires fork rebase via upgrade-forks.sh. + Mark patch as 'Phase 2.4+ work' and leave in local/patches//. + +Special cases (always SUPERSEDED regardless of fork state): +- 'bump' patches naming 'redox-scheme', 'syscall', or 'rb': managed + automatically by 'sync-versions.sh' (Cat 2 fork version +rb suffix). +- 'ecosystem-pins' patches: managed by Local Fork Supremacy Policy + + AGENTS.md 'Latest-upstream-before-freeze rule'. + +This decision tree is wired into the operator workflow by Phase 2.1 +audit + Phase 2.2 manual review + SUPERSEDED.md audit log entries. +Future fork-upstream sync operators should run 'verify-patch-content.sh' +on every fork upgrade and apply this decision tree before any attempt to +reapply orphan patches. + ### Structure ```