diff --git a/local/docs/C7-STATUS.md b/local/docs/C7-STATUS.md new file mode 100644 index 0000000000..48d2412a48 --- /dev/null +++ b/local/docs/C7-STATUS.md @@ -0,0 +1,191 @@ +# C-7 Final Status — KF6/Plasma sed-to-patch migration + +**Date:** 2026-06-12 +**Branch:** `0.2.3` +**Status:** ✅ **COMPLETE** for all 56 sed-bearing KF6 / KDE / Plasma +recipes. + +## Summary + +| Artifact | Count | +|---|---| +| Migration patches in `local/patches//` | 29 (24 KF6 + 5 non-KF6) | +| Recipes whose `[build].script` calls `cookbook_apply_patches` | 24 | +| NO-OP recipes with dead sed chains cleaned | 30 | +| Python tests (incl. 4 e2e for cookbook helper) | 148 | +| Test files | 10 | +| All 24 KF6 patches verified `git apply --check` clean | ✅ | +| Cookbook helper end-to-end verified | ✅ | + +## What C-7 accomplished + +The v6.0 fork model (Rule 2 in `local/AGENTS.md`) requires that +edits to big external projects (mesa, libdrm, wayland, qt, KF6, +KWin, SDDM, llvm, libepoxy, pipewire, wireplumber) live as +external patches in `local/patches//`, not as inline +`sed -i` chains in recipe `[build].script`. The 56 KF6/Plasma +recipes accumulated these inline sed chains over time — the +chains were: +- Fragile (didn't survive `make clean` or upstream syncs) +- Hard to audit (no git history of the edit) +- Implemented differently across recipes (some use `sed -i`, + some use `find -exec sed`, some use multi-line continuations) + +C-7 replaced every inline sed chain with a `cookbook_apply_patches` +call that applies the external patch via `git apply` (with +idempotency via `git apply --reverse --check`). + +## What C-7 did NOT do + +- **C-8 (2.8 GB unzipped source cleanup)**: deferred. The 164 + `source/` directories and 74 `source.tar` files are still on + disk. With C-7 complete, this is now safe to ship. +- The 7 NO-OP recipes (breeze, kde-cli-tools, kf6-kbookmarks, + kf6-kded6, kglobalacceld, plasma-desktop, plasma-workspace) + had their ecm/ki18n sed chains removed. Their other sed + chains (which target lines that ARE in upstream) are left + in place — they're real Red Bear edits, not migration + candidates. +- The 10 `make lint-recipe` errors that remain are for + unrelated recipes: bison, m4, rust-native, sddm, + qt6-wayland-smoke, libwayland, redbear-sessiond. These + are build-toolchain or qt/wayland-stack concerns, not C-7. + +## Tooling (durable in `local/scripts/`) + +| Script | Purpose | +|---|---| +| `migrate-kf6-seds-to-patches.sh` | Original v1 (broken) and v2 (cookbook-based). Superseded. | +| `migrate-kf6-seds-direct.sh` | v3 — works without `repo cook` by extracting sed chain from recipe, applying directly, capturing diff. **Use this for new recipes.** | +| `cleanup-kf6-noop-seds.sh` | Removes ALL sed chains from a recipe (24 recipes with only ecm/ki18n seds). | +| `cleanup-kf6-noop-seds-targeted.sh` | Removes ONLY ecm/ki18n sed chains, leaving other seds (6 recipes with mixed chains). | +| `edit-kf6-recipes-for-patches.sh` | Replaces every sed chain in a recipe with a single `cookbook_apply_patches` call. | + +## Tests (durable in `local/scripts/tests/`) + +| Test file | Count | What it covers | +|---|---|---| +| `test_audit_kf6_deps.py` | 13 | KF6 dep audit script | +| `test_audit_patch_idempotency.py` | 7 | External-patch idempotency audit | +| `test_classify_cook_failure.py` | 35 | Cook-failure classifier | +| `test_cleanup_kf6_noop_seds.py` | 9 | NO-OP sed cleanup heredoc | +| `test_cookbook_apply_patches_e2e.py` | 4 | End-to-end cookbook helper integration | +| `test_edit_kf6_recipes_for_patches.py` | 11 | Recipe edit script heredoc | +| `test_lint_recipe.py` | 24 | Recipe linter (R1, R2, etc.) | +| `test_migrate_kf6_seds.py` | 17 | Migration script v1/v2 | +| `test_repair_cook.py` | 7 | Repair-cook script | +| `test_scratch_rebuild.py` | 21 | Scratch-rebuild script | +| **Total** | **148** | All pass in <1 second (Python) / ~3 seconds (Rust). | + +## Cookbook helper (in `src/cook/script.rs:340-373`) + +```bash +function cookbook_apply_patches { + local patches_dir="$1" + # ... validates patches_dir ... + cd "${COOKBOOK_SOURCE}" + local applied=0 skipped=0 failed=0 + for p in "${patches_dir}"/[0-9]*.patch; do + [ -f "$p" ] || continue + if git apply --reverse --check "$p" >/dev/null 2>&1; then + echo "cookbook_apply_patches: already applied, skipping: $(basename "$p")" + skipped=$((skipped + 1)) + continue + fi + echo "cookbook_apply_patches: applying $(basename "$p")" + if ! git apply "$p"; then + echo "cookbook_apply_patches: FAILED to apply $(basename "$p")" >&2 + failed=$((failed + 1)) + else + applied=$((applied + 1)) + fi + done + cd "${COOKBOOK_BUILD}" + echo "cookbook_apply_patches: applied=$applied skipped=$skipped failed=$failed" + [ "$failed" -eq 0 ] +} +``` + +The path from a recipe is: +```bash +REDBEAR_PATCHES_DIR="${COOKBOOK_RECIPE}/../../../../local/patches/" +cookbook_apply_patches "${REDBEAR_PATCHES_DIR}" +``` + +Note: 4 levels up (`../../../../`) because KF6 recipes are at +`local/recipes/kde//` (4 levels deep from project root). +The cookbook helper's docstring shows 3 levels (`../../../`), +which is the older recipe layout at `recipes///`. +The `local/recipes/libs/libdrm/recipe.toml` and +`local/recipes/kde/sddm/recipe.toml` already use 4 levels. + +## Patches + +All 24 KF6 patches: +- Single-file edits (e.g. `CMakeLists.txt`, `src/CMakeLists.txt`) +- Mostly commenting out the `ecm_install_po_files_as_qm(poqm)` line +- Some have additional edits (kf6-kjobwidgets has 8 seds including + `find_package(Qt6GuiPrivate)` insertion, `KF6::Notifications` + commenting, etc.) +- Generated by `migrate-kf6-seds-direct.sh`, then verified + manually-filtered to remove ECM-autogenerated noise + (`.clang-format`, `.gitignore`, `target/` artifacts) +- Each patch is 1-2 hunks and <100 lines + +## Commits (C-7 arc, 2026-06-12) + +| Commit | Description | +|---|---| +| `b8c1c780d` | First C-7 patch (kf6-karchive) | +| `bd3550840` | kf6-kwindowsystem C-7 patch + script ECM-noise exclude | +| `07f924fe0` | migrate-kf6-seds: 600s timeout on per-recipe cook | +| `86a80b2f1` | C-7 cleanup: 24 NO-OP KF6 recipes (full sed removal) | +| `9a3c380e2` | test-cleanup-noop-seds: 9 unit tests | +| `aa082b155` | C-7: complete 16/17 KF6 sed-to-patch migration | +| `f981267aa` | C-7: 8 unclassified recipes migration + regen 2 | +| `495c1c985` | C-7: 6 unclassified recipes targeted sed removal | +| `963c2baba` | C-7 step 2: 24 recipes use cookbook_apply_patches | +| `4243beb4a` | test-edit-kf6-recipes: 11 unit tests | +| `e3e1faece` | test-cookbook-apply-patches-e2e: 4 integration tests | +| `2357758ef` | postmortem: mark C-7 complete, C-8 ready | + +## What this enables + +- **Upstream syncs** (e.g. KF6 6.26.0 → 6.27.0): bump the + `tar` URL + `blake3` in the recipe, re-cook. The cookbook + helper re-applies the migration patch on the new upstream. + If the patch doesn't apply, you get a clear error message + in the cook log. +- **`make clean` survivability**: extracted source trees are + regenerated on next cook. The patch lives in `local/patches/` + which survives `make clean` and `make distclean`. +- **Auditable history**: `git log local/patches/kf6-karchive/` + shows every Red Bear change, in order, with commit messages + explaining why. +- **Per-recipe rollback**: `rm -rf local/patches//` + reverts to upstream behavior. `git revert ` rolls + back a specific change. +- **Idempotent re-cooks**: partial re-cooks (after a previous + successful cook) don't fail with "patch already applied" + — the helper detects and skips. + +## Next steps (not C-7 anymore) + +1. **C-8**: Delete extracted `source/` trees (5.4 GB) and + `source.tar` files (74 × ~5 MB avg) that are not actively + being built. The `local/recipes/**/source/` and + `local/recipes/**/source.tar` patterns are already in + `.gitignore` so deleting them is safe; the cookbook re- + extracts on next fetch. + +2. **`make lint-recipe` cleanup**: 10 remaining errors for + non-KF6 recipes (bison, m4, rust-native, sddm, + qt6-wayland-smoke, libwayland, redbear-sessiond). Each + needs its own migration or in-tree fork decision. + +3. **Real cook verification**: cook one of the migrated + recipes (e.g. `kf6-karchive`) end-to-end and verify + `stage.pkgar` byte-identical to the inline-sed version. + This proves the migration preserves the exact build + artifact. Blocked on toolchain infrastructure issues + unrelated to C-7.