Trace Callers Before the Diff: A Blast-Radius Card for Shared OSS Helpers

Description and use

Step‑by‑step process for creating and using a blast‑radius card to identify all call sites of a shared helper, preventing regressions when changing timeouts.

Problem

A timeout fix for a shared helper caused a release candidate to fail because a worker still used the old signature via another package, revealing that green tests in the helper’s directory do not guarantee all import paths are safe.

Outcome

The workflow yields a reproducible blast‑radius card that prevents regressions by ensuring all call sites are considered before code changes, reducing review time and avoiding post‑release failures.

Workflow

• 1. Create BLAST_RADIUS.md with the provided template. 2. Harvest call sites using ripgrep or git grep, filtering out vendor/dist directories. 3. Paste each hit into the card with path:line. 4. Classify each hit as caller, re‑export, wrapper, test double, or noise. 5. Record exclusions with reasons (import boundary, generated file, unused extra). 6. Commit the harvest file alongside BLAST_RADIUS.md. 7. Freeze a contract table mapping call sites to inputs, old/new observables, and owner tests. 8. Edit production code only after the card and table are committed, ensuring changes stay within listed symbols. 9. Update or add tests that own the affected rows. 10. Review and merge once all tests pass and the card is complete.

Evidence

Maintainers then rebuilt the call graph by hand, which delayed the tag and exhausted scarce review time.

Source

Keep one markdown file in the branch, named BLAST_RADIUS.md, and treat it as a merge gate rather than decoration.

Source