Deprecate the insecure function in a minor release, document the safe replacement, warn at runtime, and remove it in a later major release. Semantic Versioning asks for at least one minor release carrying the deprecation before removal. If the flaw is actively exploitable, ship a safe default now and say so loudly.
What SemVer requires
The specification's FAQ answers this directly. When you deprecate part of your public API, do two things: update your documentation to let users know about the change, and issue a new minor release with the deprecation in place. Before you completely remove the functionality in a new major release, there should be at least one minor release that contains the deprecation, so users can transition smoothly. The spec also says the minor version must be incremented when public API functionality is marked as deprecated.
A timeline
| Release | What changes | Users see |
|---|---|---|
| 2.5.0 minor | Safe replacement added, old function marked deprecated | Runtime warning, docs updated |
| 2.6.0 minor | Warning points to the migration guide, optional strict mode errors on the old call | Opt in to enforcement |
| 3.0.0 major | Old function removed, safe behavior is the default | Build breaks if still used |
Keep the gap between deprecation and removal long enough for users to act. State the dates or versions publicly.
Steps
- Add the replacement first. Users need somewhere to go before you take anything away.
- Mark the old function deprecated in code, docs and types, with a message naming the replacement.
- Emit a runtime warning once per process, not on every call.
- Write the migration guide with before and after examples.
- Add the entry under Deprecated in the changelog, and a Security entry if the reason is a vulnerability. Keep a Changelog defines both categories.
- Add an opt in strict mode that fails on deprecated calls, so careful users can find usages early.
- Remove in the next major and list it under Removed.
When the flaw is urgent
The slow path assumes the risk allows it. If the old API is exploitable in common configurations, you can also change the default in a minor release behind an explicit, documented setting that restores the old behavior, if you judge the change compatible for nearly all users. Be honest about this tradeoff: changing behavior in a minor release can surprise people, and SemVer requires a major for backward incompatible changes. When in doubt, ship the secure option off by default, tell users to turn it on, and make it the default in the major.
For high severity cases, also publish an advisory that explains the risk and the mitigation, independent of the version plan.
Tell users where they stand
A deprecation nobody notices is no deprecation at all. Use every channel: the changelog, release notes, the docs, the runtime warning and the registry's deprecation feature where one exists. See the guide on the breaking change notice template for wording.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how unsafe calls in code are found, which is how you can locate callers of the function you plan to retire.
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 deprecating a function require a major version?
No. SemVer says to issue a minor release with the deprecation, and remove the function later in a major release.
How many minor releases must carry the deprecation?
At least one before removal, per the SemVer FAQ. Allow more time for widely used APIs.
Sources
Last reviewed: 19 October 2026.
