Keep the release in the changelog and add a loud YANKED tag after its date, then link to the release that replaces it. The Keep a Changelog guidance says pulled versions often vanish from changelogs and should not. People upgrading need to see why a version is unsafe and what to move to.
What the convention says
Keep a Changelog is a widely used format for human-readable change logs. Its guiding principles include an entry for every version, grouped types of changes, linkable versions and sections, the latest version first, and a displayed release date.
On yanked releases, its FAQ is direct. Yanked releases are versions that had to be pulled because of a serious bug or security issue. Often these versions do not even appear in changelogs, and it says they should. The recommended display is the version header with the date followed by the tag YANKED in square brackets. The tag is loud for a reason, so people notice it, and the brackets make it easier to parse programmatically.
A worked example
## [2.4.1] - 2026-10-19
### Security
- Fix path traversal in archive extraction. See advisory the advisory ID.
## [2.4.0] - 2026-10-02 [YANKED]
### Security
- Do not use this version. It contains the path traversal fixed in 2.4.1.
The yanked entry stays, keeps its original date, and now carries a warning. The fixing version states plainly what it changed.
Steps when you pull a release
- Publish the fixed version first, or at the same time, so users have somewhere to go.
- Mark the bad version as yanked or deprecated in the registry, using the registry's own feature. A registry may hide a version without deleting it, and existing lock files can still resolve it.
- Edit the changelog: add the YANKED tag and a one line reason.
- Add a Security entry to the fixing release with a link to the advisory.
- Tell users through the same channels you use for releases.
The guide on comparing unpublish, yank and deprecate explains what each registry action does and does not do, which matters because a yanked release may remain installable by exact version.
The Security type
Keep a Changelog defines a Security category for vulnerabilities, next to Added, Changed, Deprecated, Removed and Fixed. Use it consistently. A user scanning for the word Security in your log should find every vulnerability fix without reading everything else.
| Entry type | Use for |
|---|---|
| Security | Fixes for vulnerabilities |
| Deprecated | Features marked for removal |
| Removed | Features now gone |
| Changed | Behavior changes, including breaking ones |
Common mistakes
Do not quietly delete the entry for a bad version. Do not rewrite history in a way that hides what happened. The convention says you can rewrite a changelog to improve it, for example to add a forgotten breaking change, but the aim is accuracy, not concealment. And do not rely on the changelog alone, because most users learn about problems from scanners and advisories first.
Try it yourself
Click through it at your own pace, or open it full screen. Notice how a newly disclosed issue is surfaced to the teams running the affected version.
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
Should a yanked version stay in the changelog?
Yes. Keep a Changelog says it should, with a YANKED tag so readers notice it.
Does yanking remove the version from existing lock files?
Not necessarily. Behavior depends on the registry, so check what yanking does there.
Sources
Last reviewed: 19 October 2026.
