State the problem, the version that fixes it, what breaks, and exactly what users must change, in the changelog, the release notes and the security advisory. Under SemVer, a backward incompatible change requires a new major version. Lead with the action users need to take, not the history.
What the standards say
The Semantic Versioning specification says the major version must be incremented if any backward incompatible changes are introduced to the public API, and a minor version must be incremented if any public API functionality is marked as deprecated. A patch version is for backward compatible bug fixes.
The Keep a Changelog convention gives the format: group changes by type, using Added, Changed, Deprecated, Removed, Fixed and Security, show the release date, and put the latest version first. Its list of bad practices includes ignoring deprecations, and it says that when people upgrade it should be painfully clear when something will break.
The template
Use this structure in the release notes, and copy the key lines into the changelog.
- One line summary. What was wrong and that it is fixed, in plain words.
- Affected versions. Which releases have the problem and which release fixes it.
- What breaks. The exact behavior or API that changed. Name functions, options and defaults.
- What to do. Numbered steps to migrate, with before and after code.
- If you cannot upgrade yet. A mitigation or a workaround, and how long you will support the old line, if at all.
- How to verify. A command or check that shows the fix is in place.
- Credit and references. The advisory, the reporter if they agree to be named, and the issue.
Where to publish
| Place | What goes there |
|---|---|
| Changelog | The Security and Changed entries, linked to details |
| Release notes | The full template |
| Advisory | Affected versions, severity, fixed version |
| Package registry page | A short notice pointing to the advisory |
| Direct message to known large users | The action items, before public release if appropriate |
Why breaking and security collide
Sometimes the only safe fix removes an unsafe default or changes behavior. That is a breaking change, and it should be a major release. If the fix is urgent, also publish a backported patch on the old line when you can, with a stricter but compatible change, and be clear about which branch is supported.
Avoid hiding a breaking change inside a patch release to get faster adoption. Users who trust patch versions to be safe will upgrade automatically and break in production. That costs more trust than the delay would.
An example, abbreviated
Heading: Security fix in 3.0.0, breaking change to the default parser.
Body: Versions below 3.0.0 resolve external references by default. 3.0.0 disables this. If you rely on external references, set the explicit option shown below. To check, run the verification step. Version 2.9.x receives a compatible mitigation until the stated date.
Notice what the example leaves out: no blame, no history, no hedging. For related practices, see the guide on what counts as a breaking change in a fix PR.
Try it yourself
Click through it at your own pace, or open it full screen. See how new advisories reach teams after release, which is why a clear notice matters.
Where Safeguard fits
Safeguard scans dependencies, runs reachability analysis to show which findings your code can actually reach, and can open fix pull requests through autonomous remediation. That last feature is off by default and every category starts on Manual, so a person approves each change. You can try a free scan on a repository first.
Quick check
Does a security fix always need a major version?
Only if it introduces a backward incompatible change to the public API. A compatible fix can be a patch.
Where should the notice live?
In the changelog, the release notes and the advisory, so users find it from wherever they start.
Sources
Last reviewed: 19 October 2026.
