Trace Callers Before the Diff: A Blast-Radius Card for Shared OSS Helpers
The following labeled scenario opens this walkthrough and does not name a public repository or vendor team. A contributor proposed a timeout fix against a shared helper that twelve command modules imported through thin wrappers. The unit file beside that helper stayed green, so the change looked complete during a fast skim. A later release candidate failed because a worker still called the…
This walkthrough details a method for documenting the blast-radius of shared helpers in open source projects. The process begins with a markdown file named BLAST_RADIUS.md, which serves as a merge gate rather than mere decoration. Reviewers should be able to reconstruct the risk without having joined the issue thread. The card must include at least one sentence detailing the intended behavior change, as well as any forbidden or call site changes.
To identify the call sites, one should harvest command sites from the codebase, rather than relying on file-local tests or chat transcripts. This involves recording symbol names before making any edits and adapting commands to the specific language under review. The harvest process starts with a clean branch that tracks the issue and avoids mixed chores. Once the symbol names are recorded, the commands below can be used to classify each hit as a direct caller, re-export, test double, or noise.
Noise should only be deleted if the file cannot import the symbol at runtime, and the reason should be written beside the exclusion. A second pass with git grep can catch generated files that some ignore rules hide from rg. The call sites should then be pasted into the card with path and line information, and each hit should be classified accordingly.
Three rules govern the honesty of the card during review: every listed call site must come from a command that a stranger can rerun, every excluded path must carry a reason citing an import boundary, generated file, or unused extra, and every intended behavior change must fit one sentence.
To create a reusable inventory of the blast-radius, a Python script can be used to classify harvested lines into a table. The script labels hits as tests, reexports, or wrappers, and outputs the information in a structured format. The card should be committed alongside the BLAST_RADIUS.md file so reviewers can rerun the classification process without relying on screenshots. If the classifier and the card disagree, the card must be repaired before any production hunk is written.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
