Skip to content

style(utils): trim RunQemuImg godoc + move subprocess marker inline#41

Merged
CMGS merged 1 commit into
masterfrom
style/qemuimg-trim
May 11, 2026
Merged

style(utils): trim RunQemuImg godoc + move subprocess marker inline#41
CMGS merged 1 commit into
masterfrom
style/qemuimg-trim

Conversation

@CMGS
Copy link
Copy Markdown
Contributor

@CMGS CMGS commented May 11, 2026

Summary

Comment audit on 205 Go files turned up one trim candidate. utils.RunQemuImg's 10-line godoc duplicated the "shell out because qemu-img is authoritative" rationale that all 5 other subprocess sites in cocoonv2 keep as a 1-line // shell out because… comment next to the exec.Command call:

  • images/oci/erofs.go// shell out because no Go EROFS writer library; mkfs.erofs is authoritative.
  • images/cloudimg/inspect.go// shell out because no Go inspector covers the full disk format matrix; qemu-img is authoritative.
  • hypervisor/utils.go// shell out because no Go ext4 formatter library; mkfs.ext4 is authoritative.
  • hypervisor/cloudhypervisor/start.go// shell out: the cloud-hypervisor binary is the authoritative VMM.
  • hypervisor/firecracker/start.go// shell out: the firecracker binary is the authoritative VMM.

RunQemuImg's godoc was the only one carrying the rationale as a separate paragraph in the doc comment. Trim to:

  • Godoc keeps the actual contract (when to use, when NOT to use).
  • Subprocess justification moves onto the exec.CommandContext line for sibling parity.

Audit summary (no other actionable findings)

Senior SKILL.md walk on 205 files:

  • const/var blocks, sentinels, logging, context, file org, error wrap, no Chinese, no shadow — all clean.
  • Long comment blocks (23 of 6+ lines, 34 of 4–5 lines) reviewed — 22/23 long-blocks and a 10-sample of medium-blocks carry load-bearing engineering rationale (race conditions, perf numbers, contract enumerations, non-obvious invariants). 1 trim applied (this PR).

/simplify x3 parallel (reuse/quality/efficiency, 27 findings total) — verified each, all bogus or known-design:

  • Quality: console/resize.go "goroutine never exits" — for range closed-channel is correct Go idiom; fc/start.go "subprocess leak" — relay is intentionally detached (Setpgid); cmd/vm/status.go "no ctx.Done() at outer loop" — ctx.Done IS the first outer case; console/relay.go channel buffering — documented "caller closes conn" contract.
  • Efficiency: cmd/vm/exec.go "byte-per-read alloc" — buffer allocated once outside loop, comment explains why bufio would over-read; images/oci/oci.go imageSizer "redundant stats" — each stat is a different file (blob/kernel/initrd); cloudimg/commit.go "double ValidFile" — pre-lock probe + in-txn race-safe check, different purposes.
  • Reuse: fc/snapshot.go vs ch/snapshot.go buildSnapshotMeta — structurally different (FC trusts rec order, CH reconciles against config.json; FC mutates BootConfig, CH passes through). fc/api.go putJSON vs ch/helper.go vmPutJSON — semantically opposite (FC retries idempotent PUTs, CH calls DoAPIOnce for non-idempotent). Unifying would manufacture abstractions that hide meaningful differences.

make lint linux+darwin: 0 issues. go test ./...: green.

Test plan

  • make lint clean both GOOSes
  • go test ./... green
  • Sibling subprocess sites all carry inline // shell out… markers — pattern now uniform

The 10-line godoc duplicated the "shell out because qemu-img is
authoritative" rationale that lives inline on every other subprocess
site in cocoonv2 (oci/erofs.go, cloudimg/inspect.go, ch/start.go,
fc/start.go, hypervisor/utils.go). Trim the godoc to its actual
contract (when to use, when NOT to use) and move the shell-out
justification onto the exec.CommandContext call so the pattern matches
sibling files.
@CMGS CMGS merged commit d32a2d0 into master May 11, 2026
4 checks passed
@CMGS CMGS deleted the style/qemuimg-trim branch May 11, 2026 09:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant