A good fix PR description tells the reviewer what was found, why this change fixes it, how risky it is, and how to undo it. If a description lacks any of those, the reviewer has to rediscover them, and review time and mistakes both go up.
The fields that matter
1. The finding
Name the vulnerability identifier if one exists, the affected package, the affected version range, and where it appears in your project. Link to the advisory. A reviewer should not have to search.
2. Why this change
State the old and new versions and why this target was picked. The best answer is "the smallest release that includes the fix." If it jumps further, explain: the fixed line is unsupported, or a dependency forced it.
3. Exposure
Is the vulnerable code reachable from your application? Say how that was determined. "Reachable through function X called from module Y" is far more useful than a severity label. If it is not reachable, say so, because it changes how urgent the PR is. See the reachability demo.
4. What changed
List files touched and any packages moved in the lockfile beyond the target. Unexpected additions deserve a sentence each.
5. Test evidence
Which checks ran and passed? Which tests cover the change? If coverage is thin, say it. Honest gaps are more useful than a vague "all tests pass."
6. Risk level
Use a simple label tied to your tiers: low, medium or high, with the reason. Version distance, API changes in release notes and native components feed it.
7. Rollback
One line is enough: "Revert this squash commit to restore the previous version." If a database migration or config change is involved, say what else must be reversed. See how to roll back a bad dependency upgrade merge.
A compact template
Finding: <id or advisory link>, <package>, affected <range>
Change: <old version> to <new version> (smallest fixing release: yes or no)
Exposure: <reachable or not, with the call path>
Files: <list>, extra lockfile changes: <list or none>
Evidence: <checks passed>, <tests covering the change>
Risk: <low, medium or high>, <reason>
Rollback: <how>
What to leave out
Marketing language, severity inflation, and long pasted advisories. Link to them. The description is for a busy reviewer who has about two minutes.
Why this connects to trust
Reviewers trust PRs that show their work and distrust ones that only assert. Evidence on the PR also helps later: an auditor can see what the approver saw. The post on evidence attached fix PRs and reviewer trust covers the human side.
Quick check
Should the description be written by the tool or the person?
The tool can fill the structured fields. A person should add context only they know, such as a customer commitment or a planned migration.
Safeguard fix PRs are designed to carry this kind of evidence, including reachability, so reviewers can decide quickly. You can see how a finding looks with the free scan at gold.safeguard.sh/scan.
Last reviewed: 19 October 2026.
