What needs to happen
The eBPF codegen toolchain work in #282 answered several review questions (clang version pinning, why the committed .o is embedded rather than regenerated in the container image, why test-unit-root re-runs as root, the -idirafter multiarch workaround, etc.) by writing the rationale directly into code comments across .github/workflows/ci.yaml, Taskfile.yaml, containers/galactic-cni/Dockerfile, and internal/plumbing/ebpf/prog/doc.go. That's fine for getting the PR merged, but it leaves a lot of design reasoning embedded in comments scattered across four files instead of somewhere a reader would think to look for it.
This should move into proper documentation — likely alongside the existing docs/agents/ARCHITECTURE.md and docs/ conventions — so the eBPF toolchain's design decisions are discoverable in one place rather than only inline where the config happens to live.
Why this matters
Anyone touching CI, the Taskfile, or the Dockerfile later has to piece the reasoning back together from comments spread across unrelated files. Consolidated documentation makes the toolchain's tradeoffs (clang pinning, artifact drift checking, root-gated tests) easier to find and keep current.
Desired outcome
The design rationale currently living in code comments in ci.yaml, Taskfile.yaml, the CNI Dockerfile, and doc.go is captured in a docs page, with the inline comments trimmed back to what's needed to orient a reader at the point of the code itself.
Follow-up from ecv's review on #282.
Related to #282
What needs to happen
The eBPF codegen toolchain work in #282 answered several review questions (clang version pinning, why the committed
.ois embedded rather than regenerated in the container image, whytest-unit-rootre-runs as root, the-idiraftermultiarch workaround, etc.) by writing the rationale directly into code comments across.github/workflows/ci.yaml,Taskfile.yaml,containers/galactic-cni/Dockerfile, andinternal/plumbing/ebpf/prog/doc.go. That's fine for getting the PR merged, but it leaves a lot of design reasoning embedded in comments scattered across four files instead of somewhere a reader would think to look for it.This should move into proper documentation — likely alongside the existing
docs/agents/ARCHITECTURE.mdanddocs/conventions — so the eBPF toolchain's design decisions are discoverable in one place rather than only inline where the config happens to live.Why this matters
Anyone touching CI, the Taskfile, or the Dockerfile later has to piece the reasoning back together from comments spread across unrelated files. Consolidated documentation makes the toolchain's tradeoffs (clang pinning, artifact drift checking, root-gated tests) easier to find and keep current.
Desired outcome
The design rationale currently living in code comments in
ci.yaml,Taskfile.yaml, the CNIDockerfile, anddoc.gois captured in a docs page, with the inline comments trimmed back to what's needed to orient a reader at the point of the code itself.Follow-up from ecv's review on #282.
Related to #282