A good security changelog entry says what was wrong in plain words, which versions are affected, which versions fix it, how severe it is, and what the reader should do. Put it under a Security heading, link the advisory, and leave out exploit detail that helps attackers more than customers.
What the format convention gives you
The Keep a Changelog convention lists six types of change: Added, Changed, Deprecated, Removed, Fixed and Security, where Security is for vulnerabilities. It also says each version should have an entry, the latest version comes first, the release date is shown in ISO 8601 form, and versions and sections should be linkable. For releases pulled because of a serious bug or a security issue, it suggests marking them with a loud YANKED tag next to the date, and says such versions should appear in the changelog.
Those rules give you the skeleton. This post is about the sentences inside the Security section. For wider changelog structure, see the changelog guide.
A template
## [4.2.1] - 2026-10-19
### Security
- Fixed: the client did X when Y (advisory ID or link).
Affected: 4.0.0 to 4.2.0. Fixed in: 4.2.1.
Severity: stated rating and the scale you used.
Impact: what an attacker could do, in one sentence.
Action: upgrade to 4.2.1. If you cannot, do Z.
Credit: reporter name, if they agreed to be named.
Every field earns its place. Affected and fixed versions let a scanner or a person decide in seconds. Action tells the reader what to do now. If there is no workaround, say there is none.
Steps to write the entry
- Start with the effect on the customer, not the internal mechanism. "Authorization headers could be sent to a different host after a redirect" is clearer than naming a function.
- List the exact affected range. Test the oldest version you claim, because an inaccurate range causes either false alarms or false confidence.
- Give the fixed version, and if you backported, list each fixed line.
- State severity using a known scale and say which one. If you do not yet have a score, say it is pending rather than guessing.
- Link the advisory or CVE record when one exists, so tools can match the entry.
- Write the action in the imperative and keep it short.
- Credit the reporter only with permission.
- Review for leaks. Remove proof of concept code, internal hostnames and customer names.
What to leave out
- Working exploit steps. Describe the class of problem, not the recipe.
- Blame or speculation about whether anyone was attacked. State what you know, and say when you do not know.
- Vague phrases such as "improved security". They tell scanners and readers nothing.
- A fix buried in a Fixed line without the Security label. People scan for that heading.
Breaking security changes
If the fix changes behavior, add a second line under Changed that explains what callers must adapt, and mark the release as a major version. See shipping a breaking security fix.
Yanked releases
If you yank a version because of a security flaw, record that in the changelog with the tag the convention suggests, the date, and the replacement version. Yanking does not remove the code from mirrors or lockfiles, so also publish the advisory.
Quick check
Should every fix go under Security?
No. Use Security for vulnerabilities and Fixed for ordinary bugs, so readers can trust the heading.
Do I need a CVE to write a Security entry?
No. An advisory link helps tools, but a clear entry with affected and fixed versions is useful with or without an ID.
Safeguard's SBOM and dependency scanning and its fix pull requests, which are off by default, help your customers pick up a fixed version once your entry is out. There is a free scan to try.
Sources
Last reviewed: 19 October 2026.
