pcbjam/docs/features/fork-cleanup/00-effort-and-current-state.md

Fork cleanup: current state, effort & resulting diff

Status: measurement / planning. Authored 2026-06-17. Supersedes the baseline numbers in README.md — those were taken at KiCad HEAD ac7d733787; work has landed since. All figures here are against:

• KiCad fork HEAD cb82b64410, upstream merge-base 4bfed3f174 (jeff@rokeby.ie "Remove previous hack for dealing with ligatures").
• Reproduce any number with, in kicad/: git diff 4bfed3f174 HEAD -- <path> (working tree is clean).
• Do not trust scripts/kicad-diff-stats.sh for the total — it only recognises two author emails and now reports 0 because HEAD is authored by a teammate (this is the doc-07 bug, still unfixed). Verify line numbers before editing — they drift.

What this document answers

Per-change verdict — revert (not needed on web) / re-enable (stubbed "because web" but works) / relocate (needed, but movable to a new file + thin include) / keep / upstream-PR / config — plus the engineering effort and the resulting diff size. It reconciles docs 01–12 against the current source and against a ground-truth per-file ledger so churn is not double-counted.

Bottom line

The KiCad fork currently diverges by ~2,795 churned lines across 88 modified upstream files (+2,215 / −580). The 48 new files (+30,334 lines, ~28k of which is the WebGL GAL copy under common/gal/webgl + include/gal/webgl; SmaaAreaTex.h alone is 14,980) are policy-compliant and excluded — additive new files do not hurt a rebase.

• Pure divergence cleanup is ~16–28 engineer-days (~95–165 h at 6 productive h/day).
• Doing it fully lands at ~50 modified files / ~480–620 churned lines — a 78–83% reduction.
• A cheaper ~3–5 day pass removes ~1,460 lines (steps 1–6 below) and gets you to ~1,330 residual; the rest is diminishing-returns CMake relocation.
• Biggest single lever: CMake — ~1,399 of the 2,795 lines (half the diff) is mostly mechanical wrap-and-reindent churn that collapses to ~175–250 lines.
• Feature re-enables that need porting (3D viewer Route C, ngspice) are weeks of product work and remove almost zero diff until done — keep them out of the cleanup budget.

What is already done (since the README baseline)

Item	Doc	Churn removed	Evidence
KICAD_IPC_API gate reverts (18 files)	01	~107	Commit c39e8f8689; all 18 files byte-identical to merge-base
kiglew.h +189 GLEW-stub revert	01	~190	c39e8f8689; pristine vs upstream
opengl_gal.cpp Connect→Bind refactor revert	01	~63	c39e8f8689; pristine
KI_DIAG_* / wxFprintf diag call-site deletion	01	~41	c39e8f8689; zero KI_DIAG call sites remain (diag flags now inert even though -DKICAD_DIAG_*=1 is still passed)
CMake de-churn batches A–F (16 files)	02	~683 (CMake churn 1,702→1,019)	Kicad 6f82742e68 (F) on b5ac6dcbe4 (A–E); root 0b4d830. -O1 WASM build (pcbnew/eeschema/calculator) + 9/9 e2e, no screenshot change; build-graph proven byte-identical pre/post for the whole tree (compile+link+custom commands) → zero behavior change. Moves: KICAD_WASM_LAYER var, early-return guards, list(REMOVE_ITEM), add_shader redefine via new wasm/cmake/WasmShaderOverride.cmake, additive BUILD_KIWAY_DLL sets, pcb_calculator restructure, gerbview/pl_editor #5, navlib #6 (behavior-preserving stub de-churn). The in-place de-dup pass is complete; only Phase-B cmake/wasm/ relocation remains.
Tooltips implemented in wx fork	05	enables ~19 revert	wxwidgets/include/wx/wasm/tooltip.h + src/wasm/tooltip.cpp, wxUSE_TOOLTIPS=1
GetCurrentSelection/IsEmpty already base behavior in wx wasm	05	enables ~11 revert	wasm wxChoice inherits base GetCurrentSelection(){return GetSelection();}
Symbol-lib asset pipeline	09	0 (new files)	boot.ts seeds sym-lib-table; PCBJAM_LIB/FP plugins are additive new files
char_traits_uint16 Altium blocker fixed	08	0 (build infra)	force--included in scripts/kicad/build-kicad-target.sh:369 — makes importer re-enable safe
ngspice/SPICE source stubs do not exist	11	0	eeschema/sim/ is pristine; only a 15-line CMake stub block exists

Doc 01 is effectively closed (~401 lines already removed). The pcb_edit_frame.cpp / pgm_base.cpp churn that doc 01 originally listed is now KICAD_SCRIPTING gating — a different track (see Reverts).

The diff math — by action

Current churn ties to the 2,795-line ledger; residual = churn remaining in modified upstream files after the action.

Action	Files	Current churn	Residual	Net reduction	Confidence
Revert (dead/native-only, not needed on web)	11	~64	0	−64	HIGH
Re-enable feature (works on web, deletes gate)	11	~145	~5	−140	MED–HIGH (runtime-untested)
Relocate → new file + thin include	~26	~2,050	~330	−1,720	MED
Keep-inline (irreducibly small, needed)	~14	~120	~120	0	HIGH
Upstream-PR (vanishes on next submodule bump)	~30	~115	~115 → 0 on merge	−115 on bump	HIGH
Config-not-code (runtime setting)	3	~32	0	−32	HIGH
Native-bug-fix (restores native, keeps web gate)	2	~9	~8	−1	HIGH
TOTAL	88	~2,795	~480–620	−2,175 to −2,315

Residual sums to ~578 (relocate 330 + keep 120 + upstream 115 + re-enable 5 + native 8), dropping toward ~460 once the upstream PRs merge. The 480–620 range is mostly "how far the CMake relocation is pushed."

Double-counts resolved while reconciling: pcb_io_mgr.cpp/sch_io_mgr.cpp counted once under doc 08 (not doc 06); nng/webview/nanodbc CMake exclusions once under doc 02 (not doc 12); pcb_base_frame.* / sch_base_frame.* fswatcher guards once (docs 05 & 12 overlap); hidpi_gl_canvas.cpp once (docs 05 & 07); the eeschema ngspice CMake block (doc 11, 15 lines) is a subset of the doc-02 eeschema total, not additive.

Reverts — zero-risk diff deletion (restore upstream exactly)

~64 churn → 0.

• KICAD_SCRIPTING dead guards (~64 lines, 11 files) — Python is policy-off and never compiled, so the gates are dead; reverting restores upstream and the OFF build still links. Files: pcbnew/board_item.cpp (2), pcbnew/pcbnew_settings.cpp (2), include/pgm_base.h (2), eeschema/sch_edit_frame.cpp (2), common/tool/action_toolbar.cpp (2), pcbnew/menubar_pcb_editor.cpp (4), pcbnew/toolbars_pcb_editor.cpp (6), eeschema/toolbars_sch_editor.cpp (6), pcbnew/pcbnew.cpp (Python parts), pcbnew/pcb_edit_frame.cpp (~22), scripting/CMakeLists.txt (5). HIGH.
• Redundant wx workarounds (~11 lines) — eda_draw_frame.cpp + panel_setup_layers.cpp GetCurrentSelection()→GetSelection() (10) and dialog_sim_command.cpp IsEmpty()→GetCount()>0 (1): the wasm wxChoice already inherits the exact base behavior. No-ops. HIGH.
• Tooltip guards (~19 lines, 8 files) — wx fork ships working tooltip no-ops + wxUSE_TOOLTIPS=1, so every #ifndef __EMSCRIPTEN__ / #if wxUSE_TOOLTIPS guard in KiCad is dead. (Revert is the zero-risk win; upstreaming the wxUSE_TOOLTIPS spelling is the cleaner long-term route.) HIGH.
• fontconfig gratuitous comment/whitespace churn (~39 lines) — noise in the still-compiled native arm; copy back from upstream. HIGH.
• Native-only reverts (doc 07): KICAD_IPC_API default flip (3) + dead build-script flags KICAD_SPICE/KICAD_PCM/BUILD_GITHUB_PLUGIN (root scripts, 0 kicad churn). HIGH.

Relocate-to-new-file — needed on web, but shrinkable

~2,050 → ~330. Move the inline blob to a new TU/file; leave a ≤3-line #include/hook.

Item	Files	Current → residual	Mechanism
CMake if(EMSCRIPTEN) blocks	17 CMakeLists	~1,399 → ~175–250	Create kicad/cmake/wasm/*.cmake (does not exist yet) + a KICAD_WASM_LAYER cache var; early-return() guards; list(REMOVE_ITEM) instead of move-and-reindent; additive last-wins property sets; relocate static-kiface/stub blocks behind a 1-line include()
libcontext fiber backend	libcontext.cpp	334 → ~0 (+1 new file)	New libcontext_emscripten.cpp selected via CMake; revert the 2-line guard on upstream release_fcontext
fontconfig WASM stub	fontconfig.cpp/.h	228 → ~4	New fontconfig_wasm.cpp; native-vs-wasm compile selection; move <fontconfig/fontconfig.h> into the .cpp
gestfich web tool-launch bridge	common/gestfich.cpp	37 → ~3	EM_ASM blob → thin extern-C hook into a new wasm-layer file
static-KIFACE loader	common/kiway.cpp	33 → ~3	Move the resolver to wasm_kiface_loader.cpp or call OnKifaceStart from the bindings layer (include/kiway.h LIB_ENV_VAR 5 lines stays)
WebGL GAL src list	common/gal/CMakeLists.txt	30 → ~3	Move list(APPEND) to cmake/wasm/gal_webgl.cmake
HiDPI scale-factor	hidpi_gl_canvas.cpp	6 → ~2	Override GetScaleFactor in the wx wasm HIDPI canvas

Confidence MED — most carry link-order / static-kiface risk and need a real WASM build (docker/build.sh) to verify. The CMake relocation depends on first creating kicad/cmake/wasm/.

Re-enable features — net-negative diff (delete the gate)

KiCad-source diff deletion (cheap, do now):

• Importers (doc 08, ~95 lines) — delete if(NOT EMSCRIPTEN) / #ifndef __EMSCRIPTEN__ gates in common/CMakeLists.txt (Altium), pcbnew/CMakeLists.txt, pcb_io_mgr.cpp, eeschema/CMakeLists.txt, sch_io_mgr.cpp/.h. Altium blocker already neutralized. ⚠️ Configure-confident but runtime-untested — the Altium pcbnew loader has never been linked for WASM; smoke-test with sample Eagle + Altium files.
• Symbol viewer/chooser (doc 09, ~9 lines) — delete the two #ifdef __EMSCRIPTEN__ return nullptr gates in eeschema.cpp; assets already provisioned. ⚠️ Runtime-untested (GAL/LIB_TREE + asyncify modal).
• 3D delete-from-diff (doc 10, ~93 lines) — exporter_vrml.cpp stub (64), pcbnew_jobs_handler.{cpp,h} render job (9), pcbnew.cpp 3D panels (6), eda_3d_canvas.cpp raytracer gates (18).

NOT source diff — real porting (weeks, separate): Route C canvas blit wiring (16–40 h, new file), static model-loading plugins (24–60 h), the ngspice port (30–70 h). These cut 0 divergence lines until done — feature work, not cleanup.

Must-keep / impossible

• Collab/Yjs persistence hooks (~53 lines) — kicadCollabOnSave/OnModify extern-C call sites at the save/modify chokepoint: pcbnew/files.cpp (13), eeschema/files-io.cpp (12), pagelayout_editor/files.cpp (13), pl_editor_frame.cpp (15 → ~4 after trimming comments). No upstream listener API for drawing-sheet → can't relocate behind a notification. KEEP (trim comments).
• WebGL-GAL switch / silent Cairo fallback / warp-cursor in draw_panel_gal.cpp (~17) — genuine web code, irreducibly small inline. KEEP.
• SpaceMouse gates (~33 lines, 3D) — 3Dconnexion hardware, impossible in a browser. Collapse to a leading no-op __EMSCRIPTEN__ branch on the existing #ifdef __linux__ ladder + drop redundant null-guards (m_spaceMouse is already default-null) → ~6 residual. Only matters once 3D builds.
• wx-progress-reporter early-return (9), bs_thread_pool inline shim (16) — asyncify constraints; the proper fix lives in the wx layer / a re-vendor, not the rebase. KEEP.
• libcontext.h platform #elif (9), include/kiway.h LIB_ENV_VAR (5), kiplatform CMake routing (19), nng/IPC CMake stub, openGL_includes.h kiglew redirect (5) — irreducibly small additive guards. KEEP.
• ngspice model-data CMake stub (15) — too-many-locals V8 workaround; only removable if a rebuild proves wasm-opt -O2 now resolves it. KEEP for now.

Orphans — divergence the write-up (docs 01–12) never covers

• Drawing-sheet UUID feature (~33 lines, unconditional — no #ifdef, affects ALL builds): drawing_sheet.keywords (1), drawing_sheet_parser.cpp (24), ds_data_model_io.cpp (4), ds_data_item.h (4). Adds a stable per-item KIID for the Yjs differ and changes the .kicad_wks on-disk format unconditionally. Strong upstream-PR candidate (KiCad is adding UUIDs to other item types); until merged it is pure divergence no doc accounts for.
• Collab save/modify hooks (~53 lines) — the kicadCollabOnSave/OnModify files above; acknowledge as permanent web-needed divergence. KEEP.
• bs_thread_pool.hpp (16) — async-theme single-thread shim, not 01–12. KEEP / re-vendor.

Per-document effort & diff-reduction

Hours → days at 6 productive h/day.

Doc	Theme	Current churn	Residual	Reduction	Effort (h / days)	Risk	Verdict
01	Revert dead code	0	0	0	0–0.5 / ~0d	low	DONE (c39e8f8689)
02	CMake de-churn	~1,702 → 1,019	~175–250	−683 so far	22–38 / 3.7–6.3d	med	A–F (in-place de-dup) DONE (6f82742e68); only Phase-B cmake/wasm/ relocation remains. Build graph proven identical → zero behavior change
03	Config-not-code	~60	~3	~57	7–15 / 1.2–2.5d	low–med	4/5 → runtime config
04	Stub-TU relocation	~571	~20–31	~540–551	9–17 / 1.5–2.8d	low–med	2nd-biggest lever
05	wx-layer fixes	~37	~3	~34	3–7 / 0.5–1.2d	low	Mostly revertable now
06	Upstreamable patches	~122	~48 (→~15 post-merge)	~74+	17–39 / 2.8–6.5d	low–med	PR; UUID+collab stay
07	Native-build bugs & tooling	~8 (+root scripts)	~2	~6	4–9 / 0.7–1.5d	low	Tiny, near-zero WASM risk
08	Importers re-enable	~97	~2	~95	5–14 / 0.8–2.3d	low–med	Net-negative; runtime-untested
09	Symbol libs re-enable	~9	0	~9	1–3 / 0.2–0.5d	med	Un-gate; assets shipped
10	3D viewer (Route C)	~145	~12	~133 (diff)	40–96 / 6.7–16d	high	~93 delete cheap; rest is NEW porting
11	ngspice simulator	~15	~15	0 now	40–90 / 6.7–15d	high	Future feature; keep 15 CMake lines
12	Network stack	~91	~27	~64	11–22 / 1.8–3.7d	low–med	fswatcher→PR, kiway→relocate

Pure-cleanup total (docs 01–08 + revertible parts of 12, excluding the 3D/ngspice feature ports): ~95–165 h ≈ 16–28 engineer-days.

Recommended sequencing (by diff-reduction-per-hour)

Cumulative removed is from the live 2,795 baseline (doc 01's ~401 already gone).

#	Action	Doc	Reduction	Effort (h)	Cumulative removed	Risk
1	Stub-TU relocation (libcontext + fontconfig)	04	~540	5–11	~540	low–med
2	CMake de-dup pass (guards + REMOVE_ITEM, no relocation yet) — batches A–F DONE (6f82742e68, −683; in-place de-dup complete)	02	~700	8–14	~1,240	low–med
3	Importer re-enable (delete gates)	08	~95	5–14	~1,335	low–med
4	KICAD_SCRIPTING reverts	03/06	~64	2–4	~1,399	low
5	wx-layer + tooltip reverts	05	~30	2–4	~1,429	low
6	Config-not-code (warp cursor/hotkey/clock)	03	~32	3–7	~1,461	low
7	CMake relocation to cmake/wasm/ (the hard ~450→~200)	02	~250	12–24	~1,711	med
8	gestfich + kiway relocate	12/03	~67	6–12	~1,778	med
9	Symbol viewer/chooser un-gate	09	~9	1–3	~1,787	med
10	Upstream-PR batch (RTree, hotkey, choice.h, ngspice guard, UUID, fswatcher)	06/07/12	~115 on bump	17–39	~1,902 (post-merge)	low–med
11	Native-build bug fixes + dead-flag removal	07	~6	4–9	~1,908	low

End-state after steps 1–9 (pure cleanup, pre-merge): ~1,008 residual. After the upstream PRs land (step 10): ~895. With remaining CMake relocation + the deferred 3D/ngspice gate deletions folded in: ~480–620 residual. The collab-bridge orphans (~86) + irreducible keep-inline gates (~120) are the permanent floor.

Highest-ROI first move: stub-TU relocation (step 1) — ~540 lines for one day at the lowest risk — then the CMake de-dup pass, which is half the entire diff.

Caveats

• 480–620 is the full end-state. Steps 1–6 (~25–50 h) get you to ~1,330 residual; the rest is diminishing-returns CMake relocation.
• Relocate estimates are MED confidence — they need a real WASM build to verify link order / static-kiface behavior. Budget a build + e2e run per relocation batch.
• 3D and ngspice are weeks of feature work, not cleanup — they delete ~100 diff lines but only after dozens of porting hours; exclude from any diff-reduction budget.
• Per the project's own policy (fork-divergence research), reduce divergence in the wasm/build layer first; temporary diagnostics in kicad/wx are OK but must be reverted before commit.

Related

• README.md — the master inventory (baseline numbers now superseded by this doc).
• 07-native-build-bugs-and-tooling.md — includes the kicad-diff-stats.sh author-list bug that makes the script report 0; fix it to track the real number.