A good security release note names the CVE ID, describes the issue and its impact, lists affected and fixed versions, says how to upgrade or work around it, and credits the reporter. Publish it on disclosure day through a security advisory or release notes, and keep it easy to match against a user's version.
What the OpenSSF maintainer guide asks for
The OpenSSF guide for handling vulnerabilities lists what an embargoed notice should cover: the CVE ID, an issue description, reporter credit if applicable, affected versions, how the patch will be made available and the public disclosure date. It also says a patch should be easy to apply, and that where a fix needs breaking changes you should offer mitigations for users who cannot upgrade yet.
A template
Title: Short description of the flaw, fixed in 2.4.1
CVE: CVE-YYYY-NNNNN
Affected versions: 2.0.0 to 2.4.0
Fixed in: 2.4.1
Severity and impact: what an attacker can do, and under what conditions
What changed: one or two sentences on the fix
How to upgrade: the exact command
Workaround: if you cannot upgrade, do this
Credit: reporter name, if they agreed
Timeline: reported, fixed, released, published
Use plain words. Say what a user must do, not only what you changed.
Details that matter
| Element | Why |
|---|---|
| Exact version ranges | Users and scanners match on these |
| Machine readable data | The guide suggests an OSV schema JSON entry over HTTP so users can match the issue to their versions |
| All CVE IDs fixed in the release | Avoids missed items |
| Partial fix clearly labeled | The guide says users must understand their exposure even after patching |
| Credit | The guide says omitting credit is inappropriate unless the reporter does not want it |
Timing
The guide says many teams prefer to release on Monday, Tuesday or Wednesday and to avoid widely observed holidays. Embargo lengths vary by group. It lists under 7 days for one list, 45 days for CERT/CC and 90 days for Google, and says to treat policy deadlines as the start of a negotiation. Agree the date with the reporter where you can.
Do not over explain the exploit
The guide says withholding exploit details helps for a few days at most, since attackers can often work out the attack from the patch. Still, there is no need to hand over a working exploit in the note.
Where to publish
If you use GitHub, a published repository advisory appears in the Security tab. See publish a GitHub security advisory, a checklist and request a CVE as a maintainer. Also state the fix in the release notes of the version, and add updates to older announcements if a later release completes the fix.
Try it yourself
Click through it at your own pace, or open it full screen.
Click through and look at how a finding shows the fixed version. A good release note makes that line easy for a tool to read.
Safeguard shows fixed versions for findings in your dependencies and can open fix pull requests, which are off by default; the free scan is at gold.safeguard.sh/scan.
Quick check
Should the note come before or after the fix is available?
On disclosure day, with the fix available. Notify known downstream users earlier under an embargo if you have a process.
Do I need a CVE for every fix?
Not necessarily. Many projects request one for issues with real security impact. Follow your policy and your CNA.
Sources
Last reviewed: 19 October 2026.
