A good release note for a dependency security bump names the package, the old and new minimum versions, the advisory ID, whether your library was affected, and what users should do. Four or five plain sentences are enough, and honesty about impact matters more than polish.
What readers need to know
People read release notes with one question: do I need to act today? Scanners flag your library because of a transitive package, so users are looking for a line that settles it. If you write "bumped deps", they must dig through the diff.
The five facts
| Fact | Why it helps |
|---|---|
| Package name | Lets readers match their scanner output |
| Old and new minimum versions | Tells them whether their lockfile is already fine |
| Advisory identifier | A GHSA or CVE they can search |
| Affected or not | The decision they need |
| Action | Upgrade, add an override, or nothing |
Three templates
Not affected, bumped anyway
Raised the minimum version of parser from 2.3.0 to 2.3.1. This picks up the fix for the advisory GHSA-xxxx. Our library does not call the affected function, so we do not consider it affected. Upgrading is optional but will quiet scanners.
Affected, patched
Security: this release raises the minimum version of parser to 2.3.1 to fix GHSA-xxxx. Versions 3.0.0 to 3.2.0 of our library are affected when untrusted input reaches parseDocument. Upgrade to 3.2.1. See our advisory for details and a workaround.
Under investigation
We are assessing whether our library is affected by GHSA-xxxx in parser. We will update this note and publish a statement by a date you can meet. Until then, avoid passing untrusted input to the document API.
Replace the identifiers with real ones. Never invent an advisory ID or a version number in a published note.
Wording choices
- Say "not affected" only if you checked. Reachability tools or a code search count as checking. A hope does not.
- Use the exact version numbers. "Latest" ages badly.
- Keep marketing words out. A security note that sounds like an advertisement loses trust.
- Link rather than copy. Point to the upstream advisory and to yours, if you wrote one.
- Credit reporters when they agree to it.
Where to put it
Put it in three places: the release notes, the changelog, and, for an affected case, the advisory on your repository. Consistency matters, because users find your library through different doors.
Date it
Add the date inside the note if your release page does not show it. An old statement that says "under investigation" with no date looks abandoned.
Follow up
If you published an under investigation note, close the loop. Edit it when you decide, and say what changed. Silence after a holding note is the common failure.
Quick check
Should every bump get a security note?
Only bumps that fix a known vulnerability or that you raised for security reasons. Routine updates can stay in the normal changelog.
What if I am not sure whether I am affected?
Say so, and give a date for your next update. Then keep it.
Safeguard's dependency scanning and advisory monitoring help you collect the package and version facts for these notes. See the free scan.
Last reviewed: 19 October 2026.
